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This document contains tlie following changes. 
3151 Display Terminal 

• Chapter 8, "Reading Data from and Writing to Screens," has been updated to 
include the 3151 display everywhere a reference to the 3161 appears. 

• Appendix B, "Interrupt Processing" has been updated to include the 3151 
display everywhere a reference to the 3161 appears. 

• Appendix C, "Static Screens and Device Considerations" has been updated to 
include the 3151 display everywhere a reference to the 3161 appears. 

SINSTAL Utility Enhancements 

• Chapter 1, "Getting Started" has been updated to include the new option for 
SINSTAL (Option 12) on the Session Manager Option Menu screen. 

• Chapter 4, "Compihng a Program" has been updated to include the new option 
for SINSTAL (Option 12) on the Session Manager Option Menu screen. 

System Partition Statements 

• References to the SYSTEM statement have been replaced by the appropriate 
system partition statements: SYSPARTS, SYSPARMS, SYSCOMM, or 
SYSEND. 

Miscellaneous Changes 

• Numerous editorial and usability changes have been made throughout the book. 
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This book contains an introduction to the Event Driven Language. It does not 
contain a description of all Event Driven Language instructions. For a description 
of all Event Driven Language instructions, refer to the Language Reference. 



Chapters 1 through 8 of this book are intended for the application programmer who 
is coding in the Event Driven Language for the first time. Readers should be 
familiar with basic data processing terminology and concepts, such as input, output, 
and data sets. 

Chapters 9 through 20 are intended for application programmers who need 
information about such advanced topics as multitasking, data management from a 
program, communicating with other programs, writing reentrant programs, and 
writing graphics or sensor I/O programs. 



l-low This Book is Organized 

This book contains twenty chapters and three appendixes: 

Chapter 1, "Getting Started" describes the steps necessary to develop and run a 
simple Event Driven Language (EDL) program. 

Chapter 2, "Writing a Source Program" tells how to use EDL instructions to do 
such things as read data, write data, convert data, and manipulate data. 

Chapter 3, "Entering a Source Program" tells how to use the full-screen editor 
to enter and modify a source program. 

Chapter 4, "CompiUng a Program" shows how to use the Event Driven 
Language compiler to translate a source program to object code. 

Chapter 5, "Preparing an Object Module for Execution" shows how to use the 
linkage editor to prepare an object program for execution. 

Chapter 6, "Executing a Program" describes how to run a program that has 
been compiled and hnk-edited. 

Chapter 7, "Finding and Fixing Errors" describes a tool you can use to 
diagnose program logic errors and exception conditions. 

Chapter 8, "Reading Data from and Writing to Screens" on page 8-1 shows 
how to read and write data from display terminals. The chapter defines roll 
screens and static screens and describes how to write programs that interact with 
the operator. 

Chapter 9, "Designing Programs" defines what a program and a task are and 
describes multitasking, subroutines, program overlays, segment overlays, and 
unmapped storage. 
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Chapter 10, "Performing Data Management from a Program" describes various 
ways to do data management from a program. The chapter describes how to 
allocate, delete, rename, and open a data set. In addition, the chapter shows 
how to set the logical end of file, add records to a tape data set, and find the 
device type from a program. 

Chapter 11, "Reading and Writing to Tape" tells how to read to and write from 
a magnetic tape data set. 

Chapter 12, "Communicating with Another Program (Cross-Partition Services)" 
shows how programs can interact with each other, either within the same 
partition or between partitions. 

Chapter 13, "Communicating with Other Programs (Virtual Terminals)" shows 
how one program can load another program and how the programs can interact 
with each other. 

Chapter 14, "Designing and Coding Sensor I/O Programs" describes digital and 
analog input/output and shows how to read and write to sensor I/O devices. 

Chapter 15, "Designing and Coding Graphic Programs" shows how to code the 
instructions that produce graphic messages and draw curves on a display 
terminal. 

Chapter 16, "Controlling SpooUng from a Program" describes how a program 
can control printed output. 

Chapter 17, "Creating, Storing, and Retrieving Program Messages" shows how 
to save storage or coding time by creating messages than can be used by more 
than one program. 

Chapter 18, "Queue Processing" shows how to create queues, store data in 
queues, and retrieve data from queues. 

Chapter 19, "Writing Reentrant Code" shows how to design and write EDL 
programs that are reentrant. 

Chapter 20, "Accessing SSYSCOM through a Program" provides sample EDL 
programs that access the system common data area (SSYSCOM). 

Appendix A, "Tape Labels" shows the layout of tape labels. 

Appendix B, "Interrupt Processing" on page B-1 describes the interrupts that 
occur when a program interacts with a terminal. 

Appendix C, "Static Screens and Device Considerations" provides reference 
information on defining logical screens, SIMAGE subroutines, and the 
$UNPACK and $PACK subroutines. 






Aids in Using This Boole 

This book contains the following aids to using the information it presents: 
• A table of contents that hsts the major headings in the book. 



In example screens where you must answer a system request, the sample 
responses appear highhghted in red. 

An index of the topics covered in this book. 
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Using the Enter and Attention Keys 



This book uses the term "enter key" to mean the key that indicates that you have 
completed input to a screen and want the system to process the data you keyed in. 
It uses the term "attention key" to mean the key that indicates that you want to 
direct keyboard input to the operating system supervisor. If your keyboard does not 
have these keys, use the corresponding keys on your keyboard. 



A Guide to the Library 



Refer to the Library Guide and Common Index for information on the design and 
structure of the Event Driven Executive Hbrary, for a bibhography of related 
pubhcations, for a glossary of terms and abbreviations, and for an index to the 
entire library. 



Contacting IBIVI about Problems 



You can inform IBM of any inaccuracies or problems you find when using this book 
by completing and mailing the Reader's Comment Form provided in the back of this 
book. 

If you have a problem with the IBM Series/ 1 Event Driven Executive, refer to the 
IBM Series/ 1 Software Service Guide, GC34-0099. 
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Chapter 1. Getting Started 






This chapter is intended for people who have never coded an Event Driven 
Language (EDL) program. It describes the steps necessary to develop and run a 
simple program on the Series/ 1. If you are familiar with EDL and the EDX 
operating system, skip this chapter and go to Chapter 2. 

Specifically, this chapter shows you how to design, code, enter, compile, link edit, 
and execute an EDL program. Using a simple example program, we will show you 
all these steps. You may want to enter and run this program on your Series/ 1 to 
gain hands-on experience. 

All of the major steps in the development and execution of an EDL program are 
covered in greater detail later in this book. The following chart describes these steps 
and shows you where the material is covered: 

Write the source program (Chapter 2) Write a source program that does such 

things as read data, manipulate data, 
and write data. 

Enter the source program (Chapter 3) Enter the source program by using the 

session manager to build a data set. 

Compile the source program (Chapter 4) Compile your source program. 

Link edit the program (Chapter 5) Produce an executable load module. 

Run the program (Chapter 6) Cause your program to run or 

"execute." 

Find and fix errors (Chapter 7). Use the $DEBUG utiUty or a task 

error exit routine to help you locate 
and correct any problems in your 
program. 



Designing a Program 



The first step in the development of any program is the design of the program. You 
must be able to describe what you want the program to accompUsh. 

Typically, a program reads some data, processes the data, and writes the results. 
The sample program we have chosen does all of these things. The program requests 
that an operator enter a number at the terminal. That number is added to a storage 
area ten times, and the results are displayed on the terminal screen. 

Here are some questions you should ask when you plan a program. We have shown 
how we answered those questions in our sample program. 
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Questions 

Where is the data coming 
from and what form will it 
take? 



In Our Program 

The data is a number that 
the operator enters at the 
terminal. 



What do you want to do 
with the data and in what 
order do you want to 
process the data? 

Where do you print or 
record the results? 



The number that is entered 
from the terminal will be 
added 10 times to a storage 
area that you define. 

The results are displayed on 
the terminal screen. 



In the next section, we will show you how to implement this design in an EDL 
program. 



Coding the Program 



On the next few pages, we will show you how the design of this program was 
implemented. We will build the program step by step. We will not describe every 
possible operand of the instructions we use. (The Language Reference fully describes 
the operands for every EDL instruction.) 

The instructions and statements that make up a program are called the source 
program. They have the following general format: 






label 



operation 



operands 



where these terms have the following meanings: 

label The name you assign an instruction or statement. You can use this 

name in your program to refer to that specific instruction or statement. 
In most cases, the label is optional. Labels must begin in column 1 ; 
must begin with a letter or one of the special characters $, #, or @; 
and must be 1 to 8 characters long. 

operation The name of the instruction or statement you are coding. The 

operation can begin in column 2 and cannot extend beyond column 71. 

operands The data that is required to do an operation, or information on how 
the system is to perform the operation. 

To continue a line of code on the next line, place any nonblank character in column 
72 and continue the next Hne in column 16. 
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Starting the Program 

Any EDL program begins with the PROGRAM statement. 

A PROGRAM statement defines the address or label of the first instruction to be 
executed. The PROGRAM statement also defines the name of the primary task of 
the program. (EDL programs may consist of multiple tasks. In our sample 
program, the primary task is the only task of the program.) 

Our program statement looks hke this: 
ADDIO PROGRAM STPGM 

ADD 10 is the task name of the primary (and only) task. 

STPGM is the label of the first instruction to be executed. 

Defining Your Data 

The program needs two data areas: one to hold the input and one to hold the 
results of the process. Use the DATA statement to reserve storage for data. 

ADD10 PROGRAM STPGM 



COUNT DATA F'O' 
SUM DATA F'O' 

These DATA statements indicate that the reserved areas are type F (for fullword) 
and that the initial value of the areas is 0. In the Series/1, a "fullword" contains two 
bytes (16 bits). 

Since DATA statements do not cause any action to occur, place them either before 
the first instruction or after the last instruction. 



Retrieving Data 



The next step is to get input data into the program. In this program, we use a 
GETVALUE instruction to get the data. 



ADDIO 


PROGRAM 


STPGM 


STPGM 


GETVALUE 

• 


COUNT, 'ENTER NUMBER: 


COUNT 


• 
DATA 


F'O' 


SUM 


DATA 


F'O' 



When the GETVALUE instruction executes, the message "ENTER NUMBER: " 
appears on the terminal screen. When someone enters a number and presses the 
ENTER key, the system stores the number in the data area called COUNT. 
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Processing the Data 



This program is going to add the number that is entered from the terminal to the 
contents of storage area SUM. You need an ADD instruction to perform the 
addition. The number is going to be added to COUNT ten times. So the ADD 
instruction is placed inside a DO loop, which consists of a DO instruction and an 
ENDDO instruction. The DO instruction indicates how many times the instructions 
(in this case, an ADD instruction) are to be executed. 

ADD10 PROGRAM STPGM 

STPGM GETVALUE COUNT, 'ENTER NUMBER: ' 

LOOP DO 10, TIMES 

ADD SUM, COUNT 
ENDDO 



o 



COUNT 
SUM 



DATA 
DATA 



F'O' 
F'O' 



Obtaining the Results 

At this point, the program includes instructions to read the data and process the 
data. To print the results, you use two instructions: PRINTEXT and PRINTNUM. 



ADDIO 


PROGRAM 


STPGM 


STPGM 


GETVALUE 


COUNT, 'ENTER NUMBER 


LOOP 


DO 


10, TIMES 




ADD 


SUM, COUNT 




ENDDO 






PRINTEXT 


'@RESULT=' 




PRINTNUM 


SUM 






COUNT 
SUM 



DATA 
DATA 



F'O' 
F'O' 



The PRINTEXT instruction will print "RESULT = " on the terminal screen. The 
"@" symbol will cause "RESULT = " to be printed on a new Hne on the terminal 
screen. The PRINTNUM instruction will print the results of the process, which are 
stored in the SUM data area. 



1-4 SC34-0943 



Getting Started 



"%^ 



Ending the Program 

The program needs three more statements to be complete. The PROGSTOP 
statement stops the program execution and releases the storage allocated to the 
program. You code PROGSTOP after the last executable instruction in the 
program. The ENDPROG statement ends the program. The END statement 
signals the compiler that the program has no more source statements. 



All EDL programs must end with the ENDPROG and END statements. 
The completed program looks like this: 



ADDIO 


PROGRAM 


STPGM 


STPGM 


GETVALUE 


COUNT, 'ENTER NUMBER: 


LOOP 


DO 


10, TIMES 




ADD 


SUM, COUNT 




ENDDO 






PRINTEXT 


'0RESULT=' 




PRINTNUM 


SUM 




PROGSTOP 




COUNT 


DATA 


F'O' 


SUM 


DATA 

ENDPROG 

END 


F'O' 






The next step is to enter your program into a data set. We will show you how to 
use the session manager to enter the source program. The session manager provides 
a series of menus to help you enter a source program. This section shows you how 
to enter our sample program. For more information on entering a source program, 
see Chapter 3, "Entering a Source Program." 
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Entering the Source Program into a Data Set 



All the steps for entering the source program into a data set are listed below. If you 
want to actually enter the sample source program, follow the numbered steps. 

To load the session manager on your terminal: 

1 Press the attention key. 

2 Type $L SSMMAIN. 
J Press the enter key. 

When you press the enter key, the logon screen appears: 



o 



SSMMLOG: THIS TERMINAL IS LOGGED ON TO THE SESSION MANAGER- 
ENTER 1-4 CHAR USER ID ==> 
(ENTER LOGOFF TO EXIT) 

ALTERNATE SESSION MENU ==> 
(OPTIONAL) 



09:55:31 
10/24/82 



To begin a session: 

1 Type a unique user identification (called a user ID). The user id can be 1 to 4 
characters long. This chapter uses ABCD as the user ID. 

2 Press the enter key. 



$SMMLOG: THIS TERMINAL IS LOGGED ON TO THE SESSION MANAGER - 

09:55:31 
ENTER 1-4 CHAR USER ID ==> ABCD 10/24/82 

(ENTER LOGOFF TO EXIT) 

ALTERNATE SESSION MENU ==> 
(OPTIONAL) 






o 
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The Primary Option Menu appears on the screen. To enter a source program into a 
data set, select option 1 (TEXT EDITING). 



1 Type 1 on the SELECT OPTION Une. 

2 Press the enter key. 



$SMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



SELECT OPTION ==> 1 



PRESS PF3 TO EXIT 
10:00:00 



10/24/82 



ABCD 



1 - TEXT EDITING 

2 - PROGRAM PREPARATION 

3 - DATA MANAGEMENT 

4 - TERMINAL UTILITIES 

5 - GRAPHICS UTILITIES 

6 - EXEC PROGRAM/UTILITY 

7 - EXEC $JOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTIC AIDS 

10 - BACKGROUND JOB CONTROL UTILITIES 



The SFSEDIT PRIMARY OPTION MENU appears on the screen. Use option 2 
(EDIT) to create a new data set. 

1 Type 2 on the OPTION line. 

2 Press the enter key. 

$FSEDIT PRIMARY OPTION MENU STATUS = INIT 

PRESS PF3 TO EXIT 
OPTION ===> 2 

DATASET NAME =========> (CURRENTLY IN WORK FILE) 

VOLUME NAME ==========> 

HOST DATASET ========> 

ENTER A VOLUME NAME AND PRESS ENTER FOR A DIRECTORY LIST. 

1 BROWSE 

2 EDIT 

3 READ (HOST/NATIVE) 

4 WRITE (HOST/NATIVE) 

5 SUBMIT 

6 PRINT 

7 MERGE 

8 END 

9 HELP 
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Your data set then appears. This is where you will type the source program. 



EDIT --- SSMEABCD , EDX0O2 0( 1089) COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 



I ie-k-k-k-k ***** RnTTDM (IF DATA *"*****'A"***************'A-**************************:i 

To enter the source program: 

1 Type the first hne of code. 

2 Press the enter key to cause a blank entry line to appear. 
J Type the next line of code. 

4 Press the enter key. 

J Repeat steps 3 and 4 until you have entered the entire source program. 

O When you finish entering the source program, move the cursor to the 
COMMAND INPUT line and type M (for "menu")- 



EDIT --- SSMEABCD , EDX002 0( 1089) COLUMNS 001 072 

COMMAND INPUT ===> M SCROLL ==> HALF 

***** ***** TQp Qp QATA ****************************** ***J^******'^ * ********"******* 

00010 ADDIO PROGRAM STPGM 





00020 


STPGM 


00030 


LOOP 




00040 






00050 




00060 






00070 




00080 




00090 


COUNT 




00100 


SUM 




00110 




00120 




***** 


***** 



GETVALUE 


COUNT, 'EN 


DO 


10, TIMES 


ADD 


SUM, COUNT 


ENDDO 




PRINTEXT 


'(aRESULT= 


PRINTNUM 


SUM 


PROGSTOP 




DATA 


F'O' 


DATA 


F'O' 


ENDPR06 




END 





] 



***** ***** ROTTnM OF DATA ***************************'*********'"'''''f************* 



.J 



7 Press the enter key. 



.J 



1-8 SC34-0943 



Getting Started 

The SFSEDIT PRIMARY OPTION MENU appears again. 

The next step is to write the data set to a volume. When you write the data set, you 
copy the data set from the temporary data set that SFSEDIT has been using. The 
data set name we have chosen is ADDIO and the volume name is EDX002. Select 
option 4 (WRITE) to write the data set to a volume. 

1 Type 4 on the OPTION line. 

2 Type ADDIO on the DATASET NAME hne. 

3 Type EDX002 on the VOLUME NAME hne. 

4 Press the enter key. 






$FSEDIT PRIMARY OPTION MENU STATUS = MODIFIED 

PRESS PF3 TO EXIT 
OPTION ===> 4 

DATASET NAME =========> ADD10 (CURRENTLY IN WORK DATASET) 

VOLUME NAME ==========> EDX0G2 

HOST DATASET ========> 

ENTER A VOLUME NAME AND PRESS ENTER FOR A DIRECTORY LIST. 

1 BROWSE 

2 EDIT 

3 READ (HOST/NATIVE) 

4 WRITE (HOST/NATIVE) 

5 SUBMIT 

6 PRINT 

7 MERGE 

8 END 

9 HELP 



A prompt appears on the bottom of the screen. Type Y and press the enter key. 



WRITE TO ADDIO ON EDX002 (Y/N)? Y 
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A message appears on the bottom of the screen. This message means that your 
source program is 12 Unes long and has been written to volume EDX002. 



12 LINES WRITTEN TO ADDIO ,EDX0O2 



Now that you have entered and written the source program to a data set, return to 
the Session Manager Primary Option Menu. 

1 Type 8 on the OPTION line. 

2 Press the enter key. 

SFSEDIT PRIMARY OPTION MENU STATUS = SAVED 

OPTION ===> 8 

DATASET NAME =========> (CURRENTLY IN WORK FILE) 

VOLUME NAME ==========> 

HOST DATASET ========> 

ENTER A VOLUME NAME AND PRESS ENTER FOR A DIRECTORY LIST. 

1 BROWSE 

2 EDIT 

3 — - READ (HOST/NATIVE) 

4 WRITE (HOST/NATIVE) 

5 SUBMIT 

6 PRINT 

7 MERGE 

8 — - END 

9 HELP 
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Compiling Your Source Program 



Now that you have coded and entered the source program into a data set, the next 
step is to compile it into object code. Object code is code that the computer can 
read. To compile the source program, use $EDXASM, the EDX compiler. This 
section shows you how to compile the sample program. For more information on 
compiUng a source program, see Chapter 4, "Compihng a Program." 

Before you actually begin to compile, you must allocate a data set to hold the output 
(the object code). Start by selecting option 3 (DATA MANAGEMENT). 

1 Type 3 on the SELECT OPTION Une. 

2 Press the enter key. 






$SMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



SELECT OPTION ==> 3 



1 - TEXT EDITING 

2 - PROGRAM PREPARATION 

3 - DATA MANAGEMENT 

4 - TERMINAL UTILITIES 

5 - GRAPHICS UTILITIES 

6 - EXEC PROGRAM/UTILITY 

7 - EXEC $JOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTIC AIDS 

10 - BACKGROUND JOB CONTROL UTILITIES 



PRESS PF3 TO EXIT 
10:42:07 



10/24/82 



ABCD 
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The Data Management Option Menu appears on the screen. To allocate your object 
code data set, select option 1 ($DISKUT1). 

1 Type 1 on the SELECT OPTION hne. 

2 Press the enter key. 



$SMM03 SESSION MANAGER DATA MANAGEMENT OPTION MENU- 
ENTER/SELECT PARAMETERS: 

SELECT OPTION ==> 1 



PRESS PF3 TO RETURN 



1 - SDISKUTl 

2 - $DISKUT2 

3 - $C0PYUT1 

4 - $COMPRES 

5 - $COPY 

6 - $DASDI 

7 - SINITDSK 

8 - $MOVEVOL 

9 - $IAMUT1 

10 - $TAPEUT1 

11 - $HXUT1 

12 - $INSTAL 



DISK(ETTE) ALLOCATE, LIST DIRECTORY) 
DISK(ETTE) DUMP/LIST DATASETS) 
DISK(ETTE) COPY DATASETS/VOLUMES) 
DISK(ETTE) COMPRESS A VOLUME) 
DISK{ETTE) COPY DATASETS/VOLUMES) 
DISK(ETTE) SURFACE INITIALIZATION) 
DISK(ETTE) INITIALIZE/VERIFY) 
COPY DISK VOLUME TO MULTI-DISKETTES) 
INDEXED ACCESS METHOD UTILITY PROGRAM) 
TAPE ALLOCATE, CHANGE, COPY) 
H-EXCHANGE DATASET UTILITY) 
INSTALL/UPDATE A SOFTWARE PACKAGE) 



WHEN ENTERING THESE UTILITIES, THE USER IS EXPECTED 
TO ENTER A COMMAND. IF A QUESTION MARK (?) IS ENTERED 
INSTEAD OF A COMMAND, THE USER WILL BE PRESENTED WITH 
A LIST OF AVAILABLE COMMANDS. 



w 



O 
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The $DISKUT1 utility prompts you for the command and for information about the 
data set you want to create. Use the AL (allocate) command. Call the data set that 
will hold the object code ADDOBJ. Allocate a 25-record data set and use the 
default data type. 

1 Type AL on the COMMAND (?) Hne. 

2 Press the enter key. 

3 Type ADDOBJ on the MEMBER NAME hne. 

4 Press the enter key. 

5 Type 25 next to the HOW MANY RECORDS? prompt. 
O Press the enter key. 

7 Type Y next to the DEFAULT TYPE - DATA - OK (Y/N)? prompt. 

Press the enter key. 

■ ■ " ■ — ~ — -v 

LOADING $DISKUT1 nnP, hh:mm:ss, LP= xxxx, PART= yy 

$DISKUT1 - DATA SET MANAGEMENT UTILITY I 

USING VOLUME EDXQG2 

COMMAND (?): AL 

MEMBER NAME: ADDOBJ 

HOW MANY RECORDS? 25 

DEFAULT TYPE = DATA - OK (Y/N)? Y 

ADDOBJ CREATED 

COMMAND (?): EN 

A message appears teUing you that the ADDOBJ data set has been created. Enter 
the EN (end) command to return to the Data Management Option Menu screen. 

1 Type EN next to the COMMAND (?) prompt. 

2 Press the enter key. 

The next step is to return to the Session Manager Primary Option Menu to compile 
your program. To return to that menu, press the PF3 key. 
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From the Session Manager Primary Option Menu, select option 2 (PROGRAM 
PREPARATION) to prepare to compile your program. 

/ Type 2 on the SELECT OPTION line. 

2 Press the enter key. 



SSMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



SELECT OPTION ==> 2 



10/24/82 



PRESS PF3 TO EXIT 

11:12:07 

ABCD 



1 - TEXT EDITING 

2 - PROGRAM PREPARATION 

3 - DATA MANAGEMENT 

4 - TERMINAL UTILITIES 

5 - GRAPHICS UTILITIES 

6 - EXEC PROGRAM/UTILITY 

7 - EXEC $JOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTIC AIDS 

10 - BACKGROUND JOB CONTROL UTILITIES 



The Program Preparation Option Menu appears on your screen. To compile the 
source program, select option 1 ($EDXASM COMPILER). 



/ Type 1 on the SELECT OPTION Une. 
2 Press the enter key. 






$SMM02 SESSION MANAGER PROGRAM PREPARATION OPTION MENU- 



ENTER/SELECT PARAMETERS: 

SELECT OPTION ==> 1 



PRESS PF3 TO RETURN 



1 - $EDXASM COMPILER 

2 - $EDXASM/$EDXLINK 

3 - $S1ASM ASSEMBLER 

4 - $COBOL COMPILER 

5 - $FORT FORTRAN COMPILER 

6 - $PLI COMPILER/$EDXLINK 

7 - SEDXLINK LINKAGE EDITOR 

8 - $XPSLINK LINKAGE EDITOR FOR SUPERVISORS 

9 - $UPDATE 

10 - $UPDATEH (HOST) 

11 - $PREFIND 

12 - SPASCAL COMPILER/$EDXLINK 

13 - $EDXASM/$XPSLINK FOR SUPERVISORS 

14 - $MSGUT1 MESSAGE SOURCE PROCESSING UTILITY 
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The SEDXASM Parameter Input Menu appears on your screen. You must enter the 
name of your source program (data set ADD 10 on volume EDX002) and your 
object output (data set ADDOBJ on volume EDX002). 

1 Type ADD10,EDX002 next to SOURCE INPUT (NAME,VOLUME). 

2 Type ADDOBJ,EDX002 next to OBJECT OUTPUT (NAME,VOLUME). 
J Press the enter key. 

$SMM0201: SESSION MANAGER $EDXASM PARAMETER INPUT MENU 



ENTER/SELECT PARAMETERS: 

SOURCE INPUT (NAME, VOLUME) ==> ADD1O,EDX0O2 

OBJECT OUTPUT (NAME, VOLUME) ==> ADDOBJ, EDX002 

OPTIONAL PARAMETERS ==> 
(SELECT FROM THE LIST BELOW) 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 



PRESS PF3 TO RETURN 



AVAILABLE PARAMETERS: 
NOLIST 

LIST TERMINAL-NAME 
ERRORS TERMINAL-NAME 
CONTROL DATA SET. VOLUME 
OVERLAY # 



ABBREVIATION: 
NO 

LI TERMINAL-NAME 
ER TERMINAL-NAME 
CO DATA SET, VOLUME 
OV # 



DESCRIPTION: 

USED TO SUPPRESS LISTING 
USE LIST * FOR THIS TERMINAL 
USE ERRORS * FOR THIS TERMINAL 
$EDXASM LANGUAGE CONTROL DATASET 
# IS NUMBER OF AREAS FROM 1 TO 6 



DEFAULT PARAMETERS: 
LIST $SYSPRTR CONTROL $EDXL.ASMLIB OVERLAY 6 



SEDXASM then compiles the source program into object code and puts the object 
code into data set ADDOBJ. This data set is used as input in the next step, 
"Creating a Load Module." 

The information Hsted under DEFAULT PARAMETERS means that the compiler 
will print a listing of the program on the system printer, SSYSPRTR. 
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As the compilation runs, the following appears on your screen. 

r 

LOADING $JOBUTIL nnP, hh:mm:ss, LP= xxxx, PART= yy 

REMARK 

ASSEMBLE ADD1Q,EDX0O2 TO ADDQBJ ,EDXQ02 

*** JOB - SEDXASM - STARTED AT 11:21:56 00/00/00 *** 

JOB $EDXASM ($SMP02O1) USERID=ABCD 

LOADING SEDXASM nnP, hh:mni:ss, LP= xxxx, PART= yy 

ASSEMBLY STARTED 1 OVERLAY AREA ACTIVE 
COMPLETION CODE = -1 

$EDXASM ENDED AT 11:22:55 

$JOBUTIL ENDED AT 11:22:56 

PRESS ENTER KEY TO RETURN 



1 g 



If the screen fills up before displaying PRESS ENTER KEY TO RETURN, press 
the enter key. 

A completion code of — 1 means that your program compiled successfully. Any 
completion code other than — 1 means the program did not compile successfully. 

Checking Your Compiler Listing 

The compiler prints a Hsting that consists of statistics, source code statements and 
object code, undejfined or external symbols, and a completion code. 

If you do not receive a completion code of — 1 , check your hsting for errors, fix 
them in your source data set, and compile the program again. For information on 
fixing compiler errors, see "Checking Your Compiler Listing and Correcting Errors." 

If you receive a completion code of — 1 : 

1 Press the enter key to return to the SEDXASM Parameter Input Menu. 
Z, Press the PF3 key to return to the Program Preparation Option Menu. 
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Creating a Load Module 



The last step is creating a load module. A load module is a program that is ready to 
run or "execute" on the system. In this example, we use the linkage editor, 
SEDXLINK, to create the load module. SEDXLINK LINKAGE EDITOR is 
option 7 on the Program Preparation Option Menu. 



/ Type 7 on the SELECT OPTION Une. 
2 Press the enter key. 



c 



$SMM02 SESSION MANAGER PROGRAM PREPARATION OPTION MENU- 



ENTER/SELECT PARAMETERS: 
SELECT OPTION ==> 7 



PRESS PF3 TO RETURN 



1 - $EDXASM COMPILER 

2 - $EDXASM/$EDXLINK 

3 - $S1ASM ASSEMBLER 

4 - $COBOL COMPILER 

5 - $FORT FORTRAN COMPILER 

6 - $PLI COMPILER/$EDXLINK 

7 - SEDXLINK LINKAGE EDITOR 

8 - $XPSLINK LINKAGE EDITOR FOR SUPERVISORS 

9 - $UPDATE 

IG - $UPDATEH (HOST) 

11 - $PREFIND 

12 - $PASCAL COMPILER/SEDXLINK 

13 - $EDXASM/$XPSLINK FOR SUPERVISORS 

14 - $MSGUT1 MESSAGE SOURCE PROCESSING UTILITY 
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The SEDXLINK Parameter Input Menu appears on your screen. Enter an asterisk 
(*) next to EXECUTION PARM to indicate that you want the system to prompt 
you for linkage editor statements. 

1 Type an asterisk on the EXECUTION PARM line. 

2 Press the enter key. 

$SMM02G7: SESSION MANAGER $EDXLINK PARAMETER INPUT MENU 



ENTER/SELECT PARAMETERS: 



EXECUTION PARM ==> * 



PRESS PF3 TO RETURN 



ENTER A CONTROL DATA SET NAME. VOLUME OR 
AN ASTERISK (*) FOR INTERACTIVE MODE. 

OUTPUT DEVICE (DEFAULTS TO $SYSPRTR) ==> 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 



$EDXLINK displays the following screen: 



LOADING $JOBUTIL nnP, hh:mm:ss, LP= xxxx, PART= yy 

REMARK 

$EDXLINK * 

*** JOB - SEDXLINK - STARTED AT 11:27:16 11/13/82 *** 

JOB $EDXLINK ($SMPQ207) USERID=ABCD 

LOADING SEDXLINK nnP, hh:inm:ss, LP= xxxx, PART= yy 

$EDXLINK - EDX LINKAGE EDITOR 



SEDXLINK INTERACTIVE MODE 
DEFAULT VOLUME = EDX002 

STMT (?): 



"^ 






Next, enter an INCLUDE statement to indicate which object module to use. 
(Remember, the object module is ADDOBJ.) Then, enter a LINK statement to 
indicate the name of the output data set. When you enter the name of this data set 
(in this case, ADDPGM), the system allocates the data set. 
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1 Type INCLUDE ADDOBJ,EDX002 next to STMT (?). 

2 Press the enter key. 



LOADING $JOBUTIL nnP, hh:mm:ss, LP= xxxx, PART= yy 

REMARK 

$EDXLINK * 

*** JOB - SEDXLINK - STARTED AT 11:27:16 11/13/82 *** 

JOB $EDXLINK ($SMP02O7) USERID=ABCD 

LOADING $EDXLINK nnP. hh;nim:ss, LP= xxxx, PART* yy 

$EDXLINK - EDX LINKAGE EDITOR 



$EDXLINK INTERACTIVE MODE 
DEFAULT VOLUME = EDXO02 

STMT (?): INCLUDE ADDOBJ , EDX002 






/ Type LINK ADDPGM,EDX002 next to STMT (?). 
2 Press the enter key. 



LOADING $JOBUTIL nnP, hh:nm:ss, LP= xxxx, PART= yy 

REMARK 

$EDXLINK * 

*** JOB - $EDXLINK - STARTED AT 11:27:16 11/13/82 *** 

JOB $EDXLINK ($SMP02O7) USERID=ABCD 

LOADING $EDXLINK nnP, hh:mm:ss, LP= xxxx, PART= yy 

$EDXLINK - EDX LINKAGE EDITOR 



$EDXLINK INTERACTIVE MODE 
DEFAULT VOLUME = EDX002 

STMT {?):LIMK ADDPGM,EDX002 



A completion code of — 1 means that the hnk edit completed successfully. If you do 
not receive a completion code of — 1 , check your listing for errors, fix them, and Unk 
edit the program again. After the system indicates that the link edit is successful, 
return to the Primary Option Menu to execute your program by doing the following. 

1 Type EN next to STMT (?). 

2 Press the enter key. 

J Press the PF3 key to return to the Program Preparation Option Menu. 
4 Press the PF3 key again. 
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Running Your Program 



To run (or execute) your program, select option 6 (EXEC PROGRAM/UTILITY). 
/ Type 6 on the SELECT OPTION line. 
Ji Press the enter key. 



$SMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



SELECT OPTION ==> 6 



10/24/82 



PRESS PF3 TO EXIT 

11:42:07 

ABCD 



1 - TEXT EDITING 

2 - PROGRAM PREPARATION 

3 - DATA MANAGEMENT 

4 - TERMINAL UTILITIES 

5 - GRAPHICS UTILITIES 

6 - EXEC PROGRAM/UTILITY 

7 - EXEC SJOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTIC AIDS 

10 - BACKGROUND JOB CONTROL UTILITIES 



The Execute Program/Utility menu appears. You must enter the program name 
(ADDPGM) and volume (EDX002). Then, type asterisks (*) next to the data sets 
not used. 
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1 Type ADDPGM,EDX002 next to PROGRAM/UTILITY 

(NAME,VOLUME). 

2 Type an asterisk in the DATA SET 1, DATA SET 2, and DATA SET 3 
fields. 

J Press the enter key. 






$SMM06 SESSION MANAGER EXECUTE PROGRAM/UTILITY- 
ENTER/SELECT PARAMETERS: 



PROGRAM/UTILITY (NAME. VOLUME) 
DYNAMIC STORAGE (OPTIONAL) 

PARAMETERS ===> 



=> ADDPGM, EDX002 



PRESS PF3 TO RETURN 



DATA SET 1 (NAME. VOLUME / * = DSl NOT USED) ===> * 
DATA SET 2 (NAME, VOLUME / * = DS2 NOT USED) ===> * 
DATA SET 3 (NAME, VOLUME / * = DS3 NOT USED) ===> * 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 

NOTE: IF A DATA SET (DSl, DS2 OR DS3) IS NOT USED, 

AN ASTERISK (*) MUST BE ENTERED IN THE DATA SET FIELD. 






The following text appears on the terminal: 



LOADING $JOBUTIL nnP, hh:nim:ss, LP= 

REMARK 

EXECUTE PROGRAM/UTILITY: ADDPGM 

*** JOB - ADDPGM - STARTED AT 11:48:22 


xxxx, PART= yy 
11/14/82 *** 


JOB AODPGM < 
LOADING ADDPGM 
ENTER NUMBER: 

V 


$SMP06) 
nnP, 


USERID=ABCD 
hh:nifn:ss, LP= 


xxxx, 


PART= 


yy 
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The program displays ENTER NUMBER on the screen and waits for you to enter a 
number. (Remember that "ENTER NUMBER" was coded on the GETVALUE 
instruction.) 

1 Type 5 next to ENTER NUMBER. 

2 Press the enter key. 



o 



v_ 



LOADING ADDP6M 
ENTER NUMBER: 5 

RESULT= 50 
ADDPGM ENDED AT 11:48:57 

SJGBUTIL ENDED AT 11:48:58 

PRESS ENTER KEY TO RETURN 



nnP, hh:mm:ss, LP= xxxx, PART= yy 



The program displays the results of the processing. The program: 

/ Stored the number you entered (5) in an area called COUNT. 

2 Added the value of COUNT to the value of SUM, which was initialized to 0. 

J Added the two values 10 times. 

4 Displayed the result (RESULT = 50) on the terminal screen. 

The PRINTEXT instruction displayed RESULT = . The PRINTNUM instruction 
displayed the value of SUM (50). 



O 

Vv 



o 
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Chapter 2. Writing a Source Program 



This chapter tells how to use the EDL instructions to handle the basic functions of 
the language: reading and writing data, data conversions, and data manipulation 
(such as moving, adding, and subtracting). 

This chapter discusses the following topics: 
Beginning the program 
Reserving storage 
Reading data into a data area 
Moving data 
Converting data 
Manipulating data 
Writing data from a data area 
Controlling program logic 
Ending the program. 

All the instructions are discussed in detail in the Language Reference. This chapter 
discusses only a subset of the the instructions and Usts them by function. 



Beginning tlie Program 

The first statement in every EDL program must be a PROGRAM statement. The 
PROGRAM statement defines several things about the program to the Event Driven 
Executive, only two of which are discussed in this section. 

Defining tlie Primary Tasic 

Two important functions of the PROGRAM statement are to define the "primary 
task" and provide the label of the first "executable instruction." 

The primary task is the first task the system starts when you load the program. 

An executable instruction causes some action to take place. For example, 
instructions that read, write, move, or perform arithmetic operations are executable 
instructions. 

The following example shows a program with task name TASKl. Its first executable 
instruction is at location START 1. 

TASKl PROGRAM STARTl 



^\ 
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Identifying Data Sets to be Used in Your Program 

Another important function of the PROGRAM statement is to identify the data sets 
that a program will use. 

The DS = keyword operand of the PROGRAM statement allows you to identify up 
to nine data sets that the program can use. A keyword operand usually contains an 
equal ( = ) sign. The "keyword" to the left of the equal sign identifies what 
information you are supplying. The keyword operand must appear, of course, 
exactly as the system expects it. For example, if you code the DS = operand as 
SD = , the system would not recognize it. You can code keyword operands in any 
order. 

When you specify data set names in the PROGRAM statement, the system opens 
the data sets when you load the program. When the program executes, all data sets 
must already exist. One way to allocate data sets is with the SDISKUTl utiHty. If a 
program uses one data set and the data set resides on the IPL volume, the 
PROGRAM statement might look hke this: 

UPDATE PROGRAM START 1,DS=TRANS 

This program uses data set TRANS on the IPL volume. 

If a program uses more than one data set and the data sets all reside on the IPL 
volume, the DS = operand would contain one set of parentheses as follows: 

UPDATE PROGRAM START1,DS=(TRANS,MASTIN,MAST0UT) 

The program uses data sets TRANS, MASTIN, and MASTOUT on the IPL 
volume. 

If the data resides on a volume other than the IPL volume, two sets of parentheses 
are required. For example: 

TASKl PROGRAM START1,DS=((DATA1,MYV0L) , MASTER) 

The program uses data set DATAl on volume MY VOL and data set MASTER on 
the IPL volume. 



Reserving Storage 

This section shows how to reserve storage for arithmetic values or character strings. 

EDL allows you to define arithmetic values in two ways: as "integer" data or as 
"floating-point" data. Integer data consists of positive and negative numbers with 
no decimal points. Floating-point data consists of positive and negative numbers 
that can have decimal points. 

For example, you can define the number 7 as either a floating-point number or an 
integer. To define the number 7.5, however, you must define it as a floating-point 
number. 
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Reserving Storage for Integers 

To reserve storage for an integer, you can use either the DATA or DC statement. 
The following DATA statement, for example, defines a storage area for a 2-byte 
signed integer. 

SUM DATA F'O' 

SUM is the name or label of the storage area. This type of storage area is often 
called a variable. The F defines a fullword (two bytes) and ' ' assigns an initial 
value of zero to the area. 

To set up more than one I -word area in one statement, you can use the duplication 
factor. The statement: 

FITABLE DATA 15F'0' 
reserves fifteen 1-word areas and assigns a zero to each. 

You can use the areas called SUM and FITABLE in data manipulation instructions 
such as ADD and SUBTRACT. 

Assigning an Initial Value 

To assign an initial value, enclose the value in apostrophes as follows: 

FIM DATA F'5280' 

The storage area called FIM will contain the decimal value 5280 throughout the 
execution of your program, unless you change it. 

You can also assign a hexadecimal value to a storage area. For example: 
XFIM DATA X'14A0' 

XFIM contains the hexadecimal value '14A0' (decimal 5280). 

Defining a Halfword or Doubleword Data Area 

You can also define a halfword (1-byte) or doubleword (4-byte) data area. The 
following statements reserve storage for halfword integers: 

MSIX DATA H'-6' 
SHVAR DATA H'O' 

MSIX contains the value — 6. 

To reserve a doubleword of storage, define a data area as follows: 

QTRMIL DATA D' 250000' 
LNGVAR DATA D ' ' 

QTRMIL occupies a doubleword of storage and contains an initial value 250 000 
(decimal). 
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Defining Floating-Point Values 

To define floating-point values, you can use either the DATA or DC statement. 
How large the number is determines how you define the storage. If the number falls 
between 10-^6 and 10^^ and contains fewer than seven significant digits, you can 
define a single-precision floating-point data area. Each single-precision 
floating-point number requires 4 bytes of storage. 

The following DATA statement defines a storage area for a single-precision 
floating-point number. 

NETPAY DATA E'OGO.OQ' 

NETPAY is the name of the storage area. The E defines a floating-point data area 
and assigns it an initial value of zero. 

To set up more than one floating-point data area, you can use the duplication factor. 
The statement 

NPTAB DATA 12E' 000.00' 

reserves storage for twelve 4-byte floating-point data areas and assigns an initial 
value of zero to each. 

Assigning an Initial Value 

To assign an initial value to a floating point data area, enclose the value in 
apostrophes as follows: 

PI DATA E '3. 14159' 

PI contains the decimal value 3.14159. 

You can also assign an initial value to a floating-point data area in exponent (E) 
notation as follows: 

PI DATA E'.314159E1' 
PI2 DATA E'314.159E-2' 

Defining an Extended-Precision Data Area 

If a floating-point number requires more than 6 and fewer than 1 5 significant digits, 
you must use extended-precision floating point. Each extended-precision 
floating-point number requires 8 bytes of storage. 

The following DATA statements define storage areas for extended-precision 
floating-point numbers: 

MSMNT DATA L' 0.000' 
MYCELLS DATA L' 15063842E12' 

Defining Character Strings 

To define character strings, you can use either the DATA or DC statement. The 
following DATA statement defines a storage area for a 6-byte character string: 

NAME DATA C'TILTON' 

NAME is the name or label of the storage area. The length of the storage area is 
the number of characters inside the apostrophes. 
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If you want an area containing blanks, you can use the duplication factor: 
BLNKS DATA IOC ' 

BLNKS contains ten blanks. 

To set up an area that contains a character string followed by blanks, define the 
storage area as follows: 

DOLCON DATA CL4'$$' 
DOLCON contains two dollar signs ($$) followed by two blanks. 

Assigning a Value to a Symbol 

The EQU statement assigns a value to a symbol. You can use the symbol (the label 
on the EQU statement) as an operand in other instructions wherever symbols are 
allowed. You must define a label before you use that label as an operand in the 
EQU statement. 

For example, you cannot code: 

ABLE EQU BAKER 
unless you have defined BAKER previously. 

The following example assigns the word value X ' 0002 ' to A. 
A EQU 2 

If you refer to the equated value by its label, the system assumes you are referring to 
a storage location. For example, if you use A in the following instruction: 

MOVE B,A 
the system moves the word at address 0002 to B. 

If, however, you want to use the equated value as the number 2, you must precede 
the label with a plus sign ( + ) as follows: 

MOVE B,+A 

This instruction moves 2 to B. 

The next example assigns the word value of A to B. 
B EQU A 

The following example shows how you can use the equated symbols in a program. 
An explanation of the numbered items follows the example. 

MOVE C,A 

MOVE C,+A 

MOVE C,+B 

MOVE C,+A,(1,BYTE) 



A EQU 2 

B EQU A 

C DATA F 
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Q Move the contents of address 0002 to C. 

Qj Move X' 0002' to C. 

B Move X' 0002' to C. 

Q Move the leftmost byte of the word value X'0002' (in this case, X'OO') to C. 

B Define A with a word value of X' 0002'. 

Q Assign B the value of A (X' 0002'). 

Defining an input/Output Area 

To define an area to read into or to write from, you must know where the data is 
coming from or where it is going. 

If you are reading or writing data from tape, disk, or diskette, you can define an 
input/output area with a BUFFER statement, a DATA statement, or a DC 
statement. 

If you are reading or writing data from a terminal, you can define an input/output 
area with a TEXT statement, a DATA statement, or a DC statement. 

If you use either a DATA statement or a DC statement, however, you must precede 
the storage area with a word (2 bytes) containing the length and count. (Refer to 
the Language Reference for information on how the system constructs a storage area 
defined by a TEXT statement.) 

Defining a BUFFER Statement 

A BUFFER statement defines a data storage area. When you read or write records 
to disk, diskette, or tape, you can use the BUFFER statement to define the buffer. 
To define a 256-byte buffer, use the BUFFER statement as follows: 

RDAREA BUFFER 256, BYTES 

RDAREA is the name of the buffer. 

A buffer contains an index, the length of the storage area, and the data storage area. 
The index and the length occupy one word (2 bytes) each. Therefore, a 256-byte 
buffer actually occupies 260 bytes of storage. For more information on the structure 
of a buffer, refer to the Language Reference. 

Defining a TEXT Statement 

Use the TEXT statement to define a message or storage area. Use the TEXT 
statement in conjunction with the PRINTEXT or READTEXT instructions. The 
PRINTEXT instruction prints the message or storage area on a terminal. The 
READTEXT instruction reads a character string from a terminal into the storage 
area defined by the TEXT statement. 

When you code a TEXT statement, the system creates an area that contains the 
length (the size of the storage area), the count (the actual number of characters in 
the storage area), and the message or storage area. The length and count occupy 
one byte each. Therefore, a 24-character message, for example, requires 26 bytes of 
storage. The maximum length of a TEXT statement is 254 bytes. 
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The following example creates the message ENTER YOUR NAME: 
LABEL2 PRINTEXT MSGl 



MSGl TEXT 'ENTER YOUR NAME:' 

The PRINTEXT instruction that references MSGl, the name of the TEXT 
statement, causes the message to appear on the terminal. 

To define a storage area for data that you will read from a terminal, code the 
following: 

ADDRESS TEXT LENGTH=30 

A READTEXT instruction can read data from a terminal into the storage area by 
referencing ADDRESS, the name of the TEXT statement. If the response entered 
from the terminal is greater than 30 characters, the system truncates the response 
after reading 30 bytes. 



Reading Data into a Data Area 






When you read data into a data area, the instruction you use depends on the kind of 
data and where it is coming from. 

If the data resides on disk, diskette, or tape, use the READ instruction. If the data 
is coming from a terminal, use either the READTEXT or GETVALUE instruction. 
If the data is alphanumeric, use READTEXT. If the data consists of one 
floating-point number or one or more integers, use GETVALUE. 

Reading Data from Disl( or Diskette 

You can read disk or diskette data sets either sequentially or directly. You always 
read a multiple of 256 bytes. An "EDX record" contains 256 bytes. 

The READ instruction reads a record from one of the data sets you specify in the 
PROGRAM statement. The following READ instruction reads a record 
sequentially from the third data set defined on the PROGRAM statement. 

READ DS3,DISKBUFF,1,0,ERR0R=RDERR0R,END=N0TF0UND 



DISKBUFF BUFFER 256, BYTES 

The system reads one record (indicated by 1 in the third operand) sequentially 
(indicated by in the fourth operand) into DISKBUFF. If no more records exist on 
the data set, the program branches to NOTFOUND. If an I/O error occurs, the 
program branches to RDERROR. Otherwise, the system places the data in the 
256-byte buffer DISKBUFF. 
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To read a data set directly, code the fourth operand with an integer greater than 
zero as follows: 

READ DS2 , BUFR, 1 , 52 , ERROR=RDERR, END=ALLOVER 



BUFR BUFFER 512, BYTES 

The system reads the 52nd record (indicated by 52 in the fourth operand) into 
BUFR. If the data set does not contain 52 records, the program branches to 
ALLOVER. If an I/O error occurs, the program branches to RDERR. Otherwise, 
the system places one record (indicated by 1 in the third operand) into the 512-byte 
buffer BUFR. 

Reading Data from Tape 

You can read tape data sets sequentially only. A tape READ retrieves a record 
from 18 to 32767 bytes long. 

The following READ instruction reads a record from a tape. 

READ DSl, BUFF, 1, 327, END=END1,ERR0R=ERR,WAIT=YES 



BUFF BUFFER 327, BYTES 

The system reads one record (indicated by 1 in the third operand). The size of the 

record is 327 bytes (indicated by 327 in the fourth operand). If no more records f i 

exist on the data set, control transfers to ENDl. If an error occurs, control transfers '\.J^ 

to ERR. The system waits for the operation to complete before continuing 

(WAIT = YES). The buffer BUFF is 327 bytes long. 

The following READ instruction reads 2 records into buffer BUFF2. 
READ DS1,BUFF2,2,327,END=END1,ERR0R=ERR,WAIT=YES 



BUFF2 BUFFER 654, BYTES 

The system reads two records (indicated by 2 in the third operand). The size of each 
record is 327 bytes (indicated by 327 in the fourth operand). If no more records 
exists on the data set, control transfers to ENDl. If an error occurs, control 
transfers to ERR. The system waits for the operation to complete before continuing 
(WAIT = YES). The buffer BUFF2 is 654 bytes long. 

Reading from a Terminal 

To read data that an operator enters on a terminal, you can use either the 
READTEXT or GETVALUE instruction. The READTEXT instruction allows you 
to read alphanumeric data (alphabetic characters, numbers, and special characters). 
With the GETVALUE instruction, you can read numbers (both integer and 
floating-point) only. 
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Reading Alphanumeric Data 

To read an alphanumeric data item into a storage area, use the READTEXT 
instruction as follows: 

READTEXT COUNTY, ' ENTER YOUR COUNTY: ' ,SKIP=1,M0DE=LINE 



COUNTY TEXT LENGTH=20 

The instruction displays the prompt ENTER YOUR COUNTY: and the system 
waits for a response. When the operator enters a name and presses the enter key, 
the system stores the text string in an area called COUNTY. 

The operand SKIP = 1 causes the system to skip one line before displaying the 
prompt. The operand MODE = LINE allows blanks in the response. 

For more information on reading alphanumeric data from terminals, see 
Chapter 8, "Reading Data from and Writing to Screens." 

Reading Numeric Data 

The GETVALUE instruction allows you to read either a single floating-point value 
or more than one integer from a terminal. The following instruction reads a 
floating-point number: 

GETVALUE BASAL, 'ENTER YOUR BASE SALARY: ', C 

TYPE=F,F0RMAT=(6,2,F) 



BASAL DATA E'O.GO' 

The instruction prompts the operator, waits for a response, reads the response, and 
stores the number in BASAL. You must have defined BASAL as a floating-point 
variable. The operand TYPE = F means that the number will be a single-precision 
floating-point number. 

The operand FORMAT = (6,2,F) says that the number will occupy six positions on 
the screen (including the decimal point), that the number will contain two digits to 
the right of the decimal point, and that the number will be an "F-type" number such 
as 325.78. 

To read more than one integer, code a third operand on the instruction as follows: 
GETVALUE HEIGHTS, 'ENTER FIVE HEIGHTS (IN INCHES): ',5 

The instruction assumes that you have defined HEIGHTS as follows: 
HEIGHTS DATA 5F'0' 
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Moving Data 



You can move data from one place in storage to another with the MOVE 
instruction. Unless you specify otherwise, the system moves one word (two bytes). 
For example, the instruction 

MOVE OLDDATA,NEWDATA 



OLDDATA DATA F'O' 
NEWDATA DATA F'O' 

moves the word at NEWDATA to OLDDATA. Note that whatever OLDDATA 
contained before the instruction was executed has been overlaid by the data in 
NEWDATA. 

To move more than one word, you must code a third operand. For example, the 
following instruction moves 12 words from NEWNAME to OLDNAME: 

MOVE OLDNAME, NEWNAME, 12 



OLDNAME DATA F'O' 
NEWNAME DATA F'O' 

To move bytes, code the third operand as follows: 

MOVE 0LDADDR,NEWADDR,(15,BYTE) ^f~^^ 



OLDADDR TEXT LEN6TH=15 
NEWADDR TEXT LENGTH=15 

This instruction moves the 15 bytes at NEWADDR to OLDADDR. To move 
doublewords, code the third operand as follows: 

MOVE OLDDESC,NEWDESC, (10, DWORD) 



OLDDESC DATA lOD'O' 
NEWDESC DATA lOD'O' 

This instruction moves the 10 doublewords at NEWDESC to OLDDESC. To move 
floating-point values, you must specify FLOAT (for single-precision) or DFLOAT 
(for extended-precision). 

MOVE TEMPS, MSMNTS, (4, FLOAT) 



TEMPS DATA 4E'O.0' 
MSMNTS DATA 4E'0.0' 

The instruction moves the four single-precision floating-point values at MSMNTS to W^ *) 

TEMPS. ^-^ 
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Converting Data 



EDL allows you to do two types of conversion, from binary to an EBCDIC 
character string and from an EBCDIC character string to binary. The CONVTB 
instruction converts from binary to an EBCDIC character string, while the 
CONVTD instruction converts from an EBCDIC character string to binary. 

Converting to an EBCDIC Character String 

If a number has been stored as a binary number, you must convert it to an EBCDIC 
character string if, for example, you want to display the number with the 
PRINTEXT instruction. 

A binary number is any variable you have defined as single-precision integer, 
double-precision integer, single-precision floating point, extended-precision floating 
point, or hexadecimal. 

You must convert any of the following data items before you can display them: 






NUMl 


DATA 


F'O' 


NUM2 


DATA 


D'O" 


PI 


DATA 


E'Q.0' 


FINMEAS 


DATA 


L'0.0' 


XTRAS 


DATA 


X'O' 



To convert a single-precision integer to an EBCDIC character string, code the 
CONVTB instruction as follows: 

CONVTB TEXT1,NUM1,PREC=S,FORMAT=(5,0,I) 



TEXTl TEXT LENGTH=5 
NUMl DATA F'O' 

The instruction converts the single-precision integer (indicated by PREC = S) in 
NUMl and stores the result in TEXTl. The FORMAT operand says that you want 
the converted output to be 5 digits long, contain digits to the right of the decimal 
point, and be an integer (I). 

To convert a double-precision integer, code the CONVTB instruction as follows: 
CONVTB TEXT2,NUM2,PREC=D,F0RMAT=(8,0,I) 



TEXT2 TEXT LENGTH=8 
NUM2 DATA D'O' 

The instruction converts the double-precision integer (indicated by PREC = D) in 
NUM2 and stores the result of the conversion in TEXT2. The FORMAT operand 
says that you want the converted output to be 8 digits long, contain digits to the 
right of the decimal point, and be an integer (I). 
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To convert a single-precision floating-point variable: 

CONVTB TEXT3,PI,PREC=F,F0RMAT=(15,4,F) 



TEXTS TEXT LENGTH=16 
PI DATA E' 0.0000' 

The instruction converts the single-precision floating-point variable (indicated by 
PREC = F) in PI and stores the result of the conversion in TEXT3. The FORMAT 
operand says that you want the converted output to be 15 digits long, contain 4 
digits to the right of the decimal point, and be a floating-point value (F). 

To convert an extended-precision floating-point variable: 
CONVTB TEXT4,0P,PREC=L,F0RMAT=(17,3,E) 



TEXT4 TEXT LENGTH=24 
OP DATA L 

The instruction converts the extended-precision floating-point variable (indicated by 
PREC = L) in OP and puts the result of the conversion in TEXT4. The FORMAT 
operand says that you want the converted output to be 17 digits long, contain 3 
digits to the right of the decimal point, and be expressed in exponent notation (E). 

Converting to Binary , 

If you read a number with the READTEXT instruction, you must convert it to V_.y 

binary before you can add, subtract, multiply, or divide. 

The CONVTD instruction converts a character string to a binary number. You can 
convert a character string that contains a number to a single-precision integer, a 
double-precision integer, single-precision floating point, or extended-precision 
floating point. 

To convert a single-precision integer to binary: 

CONVTD BINUM1,NUM1,PREC=S,F0RMAT=(5,0,I) 



BINUMl DATA F'O' 
NUMl TEXT LENGTH=5 

The instruction converts the EBCDIC character string in NUM 1 and stores the 
result in BINUMl, a single-precision integer variable (indicated by PREC = S). 

The FORMAT operand says that the data to be converted is 5 digits long, contains 
digits to the right of the decimal point, and is an integer (I). 
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To convert a a number that is greater than 32767, you must convert it to a 
double-precision integer as follows: 

CONVTD BINUM2,NUM2,PREC=D,F0RMAT=(9,Q,I) 



BINUM2 DATA D'0' 
NUM2 TEXT LENGTH=9 

The instruction converts the EBCDIC character string in NUM2 and puts the result 
in BINUM2, a double-precision integer variable (indicated by PREC = D). 

The FORMAT operand says that the data to be converted is 9 digits long, contains 
digits to the right of the decimal point, and is an integer(I). 

To convert to a single-precision floating point number, code the instruction as 
follows: 

CONVTD AVTEMP,TEMP,PREC=F,F0RMAT=(8,2,F) 



AVTEMP DATA E'0.0' 
TEMP TEXT LENGTH=9 

The instruction converts the EBCDIC character string in TEMP and stores the result 
in AVTEMP, a single-precision floating-point variable (indicated by PREC = F). 

The FORMAT operand says that the data to be converted is 8 digits long, contains 
2 digits to the right of the decimal point, and is a floating-point number (F). 

To convert to an extended-precision floating point number, code the instruction as 
follows: 

CONVTD AVCOST , COST , PREC=L , FORMAT= (15 , 3 , E) 



AVCOST DATA L'O.QO' 
COST TEXT LENGTH=20 

The instruction converts the EBCDIC character string in COST and stores the result 
in AVCOST, an extended-precision floating-point variable (indicated by PREC = L). 

The FORMAT operand says that the data to be converted is 15 digits long, contains 
3 digits to the right of the decimal point, and is expressed in exponent notation (E). 
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Converting from Floating Point to Integer 

If you want to manipulate data, both operands in the operation must be either 
floating point or integer. 

To convert a single-precision floating-point number to integer, code the FPCONV 
instruction as follows: 

FPCONV INTNUM,FPNUM,PREC=SF 



INTNUM DATA F'O' 
FPNUM DATA E'0.0' 

The instruction converts the single-precision floating-point number in FPNUM and 
stores the result in INTNUM, a single-precision integer variable. The PREC 
operand indicates that INTNUM is a single-precision integer (S) and that FPNUM 
is a single-precision floating-point number (F). 

To convert an extended-precision floating-point number to double-precision integer, 
code the FPCONV instruction as follows: 

FPCONV INTDBL,FPEXT,PREC=DL 



INTDBL DATA D'O' 
FPEXT DATA L'O.O' 

The instruction converts the extended-precision floating-point number in FPEXT u J 

and puts the result in INTDBL, a double-precision integer variable. The PREC 
operand indicates that INTDBL is a double-precision integer (D) and that FPEXT is 
an extended-precision floating-point number (L). 

Note: When you convert from floating point to integer, remember that the system 
truncates all data to the right of the decimal point. 

Converting from Integer to Floating Point 

To convert a single-precision integer to floating-point, code the FPCONV instruction 
as follows: 

FPCONV FPNUM, INTNUM, PREC=FS 



INTNUM DATA F'O' 
FPNUM DATA E'0.0' 

The instruction converts the single-precision integer INTNUM and stores the result 
in FPNUM, a single-precision floating-point variable. The first letter in the PREC 
operand (F) indicates that FPNUM is a single-precision floating-point variable. The 
second letter (S) indicates that INTNUM is a single-precision integer. 
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To convert a double-precision integer to floating-point: 
FPCONV FPEXT,INTDBL,PREC=LD 



INTDBL DATA 
FPEXT DATA 



D'O' 
L'0.0' 



The instruction converts the double-precision integer INTDBL and stores the result 
in FPEXT, an extended-precision floating-point variable. The first letter in the 
PREC operand (L) indicates that FPEXT is an extended-precision floating-point 
variable. The second letter (D) indicates that INTDBL is a double-precision integer. 

Each time you execute an instruction that converts data, the system expects the data 
to be numeric. If the conversion is successful, the value — 1 appears in the first word 
of the task control block (TCB) of the program or task issuing the instruction. (The 
label of the TCB is the label of your program or task.) If you try to convert a 
character other than a number, a conversion error occurs and the value — 1 is not 
stored as the return code. 

If, for example, a program prompts an operator for a number and he or she enters a 
letter, the system places a return code in the task code word indicating a conversion 
error. Your program can check the return code for a conversion error and print an 
error message. Notice that you must test the return code before executing any other 
instruction because the system may overlay the task code word with the return code 
of the next instruction. 

The following program shows how to check for a conversion error: 
BEGIN PROGRAM START 



CONVTD 
ERRTEST MOVE 
IF 
ENDIF 



BINUMl,NUMl,PREC=S,FORMAT=(5,0,i; 
TASKRC, BEGIN 
(TASKRC,NE,-1), GOTO, CHECK 



CHECK PRINTEXT 'CONVERSION ERROR' ,SKIP=1 
PRINTNUM TASKRC 
GOTO END 



END 


PROGSTOP 




TASKRC 


DATA 


F'O' 


BINUMl 


DATA 


F'O' 


NUMl 


TEXT 

ENDPROG 

END 


LENGTH=5 



The instructions at label ERRTEST compare the return code of the CONVTD 
instruction with the successful return code (—1). If NUMl contains a nonnumeric 
character, the system branches to CHECK. 
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Manipulating Data 



The data manipulation instructions perform arithmetic operations on single- or 
double-precision integers and single- or extended-precision floating-point numbers. 
You can also manipulate two bit-strings with logical instructions such as 
inclusive-OR and exclusive-OR. 

Manipulating Integer Data 

The instructions that manipulate integers add, subtract, multiply, or divide two 
integers. If two numbers are floating-point numbers, you must use floating-point 
instructions. 

If one number is a floating-point number and the other is an integer, use the 
FPCONV instruction to convert one of the numbers to match the form of the other. 

The instructions have the following general form: 
operation operandi, opGrand2 

The flow of data is from operandi to operandi. 

The ADD instruction adds the data in operandi to the data in operandi and stores 
the results in operandi. 

The SUBTRACT instruction subtracts the data in operandi from the data in 
operandi and stores the results in operandi. 

The DIVIDE and MULTIPLY instructions multiply or divide the data in operandi \^ 

by the data in operandi and store the results in operandi. 



Adding Integers 



The ADD instruction adds two integers. If A and B are integers, you can add A to 
B with the following instruction: 

ADD B,A 

The result of the addition replaces B. The value in A remains unchanged. 

To add two integers without altering the first operand, use the RESULT operand as 
follows: 

ADD OLDSUM, SCORE, RESULT=NEWSUM 

The instruction adds SCORE to OLDSUM and stores the result in NEWSUM. The 
values in SCORE and OLDSUM remain unchanged. 

Adding Double-Precision Integers: 

Unless you specify otherwise, EDL assumes that the integers are single-precision 
(1-word) integers. To add two double-precision (2-word) integers, specify the PREC 
operand as follows: 

ADD TOTPOP,LOCPOP,PREC=DD 

The operand PREC = DD says that both TOTPOP and LOCPOP are 
double-precision integers. 
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If only one of the operands is a double-precision integer, it must be the first 
operand. In addition, if you specify the RESULT operand, it must be a 
double-precision variable. For example: 

ADD T0WN2,T0WN1,RESULT=T0TP0P,PREC=D 

The operand PREC^D says that TOWN2 and TOTPOP are double-precision 
integers. The absence of the second letter (D or S) on the PREC operand means 
that TOWNl is a single-precision integer. 

Adding Consecutive Integers: 

To add more than one set of integers, you can specify the number of integers you 
want to add. For example: 

ADD NEWT0TS,0LDT0TS,10 

The instruction adds the 1-word integer at OLDTOTS to NEWTOTS. Then the 
instructionaddsthe wordinOLDTOTS + 2 to the wordatNEWTOTS + 2. The 
instruction continues to add until it adds the word at OLDTOTS + 18 to the word at 
NEWTOTS + 18. This instruction, then, adds the 10 consecutive words at 
OLDTOTS to the 10 consecutive words at NEWTOTS. You can specify up to 
32767 consecutive additions. 

Subtracting Integers 

The SUBTRACT instruction subtracts one integer from another. If QUERY and 
ANSWER are integers, you can subtract ANSWER from QUERY with the 
following instruction: 

'§ SUBTRACT QUERY, ANSWER 

The result of the subtraction replaces QUERY. The value in ANSWER remains 
unchanged. 

To subtract two integers without altering the first operand, use the RESULT 
operand as follows: 

SUBTRACT SALES, COSTS, RESULT=PROFITS 

The instruction subtracts COSTS from SALES and stores the result in PROFITS. 
The values in SALES and COSTS remain unchanged. 

Subtracting Double-Precision Integers: 

Unless you specify otherwise, EDL assumes that the integers are single-precision 
(1-word) integers. To subtract two double-precision (2-word) integers, specify the 
PREC operand as follows: 

SUBTRACT GROSS, DEDUCT, RESULT=NET,PREC=DD 

The instruction subtracts DEDUCT from GROSS and stores the result in NET. 
The operand PREC = DD says that GROSS, DEDUCT, and NET are all 
double-precision integers. 
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If only one of the operands is a double-precision integer, it must be the first 
operand. In addition, if you specify the RESULT operand, it must be a 
double-precision variable. For example: 

SUBTRACT ATTEND , MALES , RESULT=FEMALES , PREC=D 

The instruction subtracts MALES from ATTEND and stores the result in 
FEMALES. The operand PREC = D says that ATTEND and FEMALES are 
double-precision integers. The absence of the second letter (D or S) on the PREC 
operand means that MALES is a single-precision integer. 

Subtracting Consecutive Integers: 

To subtract more than one set of integers, you can specify the number of integers 
you want to subtract. For example: 

SUBTRACT NEWT0TS,0LDT0TS,6 

The instruction subtracts the 1-word integer at OLDTOTS from NEWTOTS. Then 
the instruction subtracts the word in OLDTOTS + 2 from the word at 
NEWTOTS + 2. The instruction continues to subtract until it subtracts the word at 
OLDTOTS + 10 from the word at NEWTOTS + 10. This instruction, then, subtracts 
the 6 consecutive words at OLDTOTS from the 6 consecutive words at NEWTOTS. 
You can specify up to 32767 consecutive subtractions. 

Multiplying integers 

The MULTIPLY instruction multiplies one integer by another. 

If M and N are single-precision integers, you can multiply M by N as follows: > 

MULTIPLY M,N 

The result of the multiphcation replaces M. 

You can also multiply an integer by a constant. The following instruction multiplies 
FEET by the constant 12: 

MULTIPLY FEET, 12 

The result of the multiplication replaces FEET. 

To multiply two integers without altering the first operand, use the RESULT 
operand as follows: 

MULTIPLY BOXES, WEIGHT, RESULT=TOTWGT 

The instruction multiphes BOXES by WEIGHT and stores the result in TOTWGT. 
The values in BOXES and WEIGHT do not change. 

Multiplying Double-Precision Integers: 

Unless you specify otherwise, EDL assumes that integers are single-precision 
(1-word) integers. To multiply two double-precision (2-word) integers, specify the 
PREC operand as follows: 

MULTIPLY LENGTH, WIDTH, RESULT=TOTAREA,PREC=DD 
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The instruction multiplies LENGTH by WIDTH and stores the result in 
TOTAREA. The operand PREC = DD says that LENGTH, WIDTH, and 
TOTAREA are all double-precision integers. 

If only one of the operands is a double-precision integer, it must be the first 
operand. In addition, if you specify the RESULT operand, it must be a 
double-precision variable. For example: 

MULTIPLY ATTEND, GAMES, RESULT=TOTATT,PREC=D 

The instruction multiphes ATTEND by GAMES and stores the result in TOT ATT. 
The operand PREC = D says that ATTEND and TOT ATT are double-precision 
integers. The absence of the second letter (D or S) on the PREC operand means 
that GAMES is a single-precision integer. 

Multiplying Consecutive Integers: 

To multiply more than one set of integers, you can specify the number of integers 
you want to multiply. For example: 

MULTIPLY SALARIES, RATES, 400 

The instruction multiphes the 1-word integer at RATES by SALARIES and stores 
the result in SALARIES. Then the instruction multiplies the word at RATES + 2 by 
the word at SALARIES + 2. The instruction continues to multiply until it multiphes 
the word at RATES + 798 by the word at SALARIES + 798. This instruction, then, 
multiplies the 400 consecutive words at RATES by the 400 consecutive words at 
SALARIES. You can specify up to 32767 consecutive multiphcations. 



The DIVIDE instruction divides one integer by another. The system stores the 
remainder in the first word of the task control block (TCB). 

If P and Q are single-precision integers, you can divide P by Q as follows: 
DIVIDE P,Q 

The result of the division replaces P. 

You can also divide an integer by a constant. The following instruction divides 
FEET by the constant 3: 

DIVIDE FEET, 3 

The result of the division replaces FEET. 

To divide two integers without altering the first operand, use the RESULT operand 
as foUows: 

DIVIDE TOTWGT , BOXES , RESU LT=B0XW6T 

The instruction divides TOTWGT by BOXES and stores the result in BOXWGT. 
The values in TOTWGT and BOXES do not change. 
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Dividing Double-Precision Integers: 

Unless you specify otherwise, EDL assumes that integers are single-precision f jj) 

(1-word) integers. To divide double-precision (2-word) integers, specify the PREC 
operand as follows: 

DIVIDE T0TSAL,N0EMPS,RESULT=AVESAL3PREC=DD 

The instruction divides TOTSAL by NOEMPS and stores the result in AVESAL. 
The operand PREC = DD says that TOTSAL, NOEMPS, and AVESAL are all 
double-precision integers. 

If only one of the operands is a double-precision integer, it must be the first 
operand. In addition, if you specify the RESULT operand, it must be a 
double-precision variable. For example: 

DIVIDE TOTATT, GAMES, RESULT=AVEATT,PREC=D 

The instruction divides TOTATT by GAMES and stores the result in AVEATT. 
The operand PREC = D says that TOTATT and AVEATT are double-precision 
integers. The absence of the second letter (D or S) on the PREC operand means 
that GAMES is a single-precision integer. 

Dividing Consecutive Integers: 

To divide more than one set of integers, you can specify the number of integers you 
want to divide. For example: 

DIVIDE SALARIES, RATES, 100 

The instruction divides the 1 -word integer at SALARIES by RATES. Then the 
instruction divides the word in SALARIES + 2 by the word at RATES + 2. The 
instruction continues to divide until it divides the word at SALARIES + 198 by the 
word at RATES + 198. This instruction, then, divides the 100 consecutive words at 
SALARIES by the 100 consecutive words at RATES. You can specify up to 32767 
consecutive divisions. 

Accessing the Remainder: 

One way to access the remainder is to use the TCBGET instruction as in the 
following example: 

DIVIDE SALARIES, RATES 
TCBGET REMAIN, $TCBCO 



REMAIN DATA F'O' 

The instruction puts the first word of the task control block, containing the 
remainder, into REMAIN. 



2-20 SC34-0943 






^^^"s. 

^^n^' 



Writing a Source Program 



Manipulating Floating-Point Data 

EDL allows you to add, subtract, multiply, and divide floating-point numbers. 
Floating-point numbers are positive and negative numbers that can have decimal 
points. 

To use floating-point instructions, you must: 

• Have the hardware floating-point feature installed on your system. 

• Include floating-point support in the supervisor when it is generated. 

• Specify FLOAT = YES on both the PROGRAM and TASK statements 
whenever you use floating-point instructions in any task within a program. 

• Define the variables you are manipulating as floating-point variables. 

Adding Floating-Point Data 

The FADD instruction adds two floating-point numbers. If A and B are 
floating-point numbers, you can add A to B with the following instruction: 

FADD B,A 

The result of the addition replaces B. The value in A remains unchanged. 

To add two floating-point numbers without altering the first operand, use the 
RESULT operand as follows: 

FADD WAGES, OVTIME,RESULT=NETPAY 

The instruction adds OVTIME to WAGES and stores the result in NETPAY. The 
values in WAGES and OVTIME remain unchanged. 

Adding Extended-Precision Floating-Point Numbers: 

Unless you specify otherwise, EDL assumes that the floating-point numbers are 
single-precision (2-word) floating-point numbers. To add two extended-precision 
(4-word) floating-point numbers, specify the PREC operand as follows: 

FADD TOTSAL,PRESAL,PREC=LL 

The operand PREC = LL says that both TOTSAL and PRESAL are 
extended-precision floating-point numbers. 

If only one of the operands is an extended-precision floating-point number, the 
PREC operand must reflect the precision. In the following example: 

FADD MSMNT1,MSMNT2,RESULT=MSMTS,PREC=LFL 

the operand PREC = LFL says that MSMNTl and MSMTS are extended-precision 
floating-point numbers and MSMNT2 is a single-precision floating-point number. 
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Subtracting Floating-Point Numbers 

The FSUB instruction subtracts one floating-point number from another. If 
OCTEMP and NOVTEMP are floating-point numbers, you can subtract 
NOVTEMP from OCTEMP with the following instruction: 

|-C''ri n/-»-ri-ijr* fti/M/TT-»«n 

rouD uLi tMrjiNUv I mP 

The result of the subtraction replaces OCTEMP. The value in NOVTEMP remains 
unchanged. 

To subtract two floating-point numbers without altering the first operand, use the 
RESULT operand as follows: 

FSUB SAL,DEDUCS,RESULT=NET 

The instruction subtracts DEDUCS from SAL and stores the result in NET. The 
values in SAL and DEDUCS remain unchanged. 

Subtracting Extended-Precision Floating-Point Numbers: 

Unless you specify otherwise, EDL assumes that the floating-point numbers are 
single-precision (2-word) floating-point numbers. To subtract two 
extended-precision (4-word) floating-point numbers, specify the PREC operand as 
follows: 

FSUB TOTSALJOTDUCS,RESULT=TOTNP,PREC=LLL 

The instruction subtracts TOTDUCS from TOTSAL and stores the result in 
TOTNP. The operand PREC = LLL says that TOTSAL, TOTDUCS, and TOTNP 
are all extended-precision floating-point numbers. 

If only one of the operands is an extended-precision floating-point number, the 
PREC operand should reflect the precision. In the following example: 

FSUB GROSS, TAXES, RESULT=NET,PREC=FLF 

the instruction subtracts TAXES from GROSS and stores the result in NET. The 
operand PREC = FLF says that GROSS and NET are single-precision and that 
TAXES is an extended-precision floating-point number. 

Multiplying Floating-Point Numbers 

The FMULT instruction multiplies one floating-point number by another. 

If M and N are single-precision floating-point numbers, you can multiply M by N as 
follows: 

FMULT M,N 

The result of the multiplication replaces M. 

You can also multiply a floating-point number by an integer constant. The 
following instruction multiplies FEET by the integer constant 12: 

FMULT FEET, 12 
The result of the multipUcation replaces FEET. 
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To multiply two floating-point numbers without altering the first operand, use the 
RESULT operand as follows: 

FMULT LENGTH, WIDTH, RESULT=AREA 

The instruction multiphes LENGTH by WIDTH and stores the result in AREA. 
The values in LENGTH and WIDTH do not change. 

Multiplying Extended-Precision Floating-Point Numbers: 

Unless you specify otherwise, EDL assumes that floating-point numbers are 
single-precision (2-word) floating-point numbers. To multiply two 
extended-precision (4-word) floating-point numbers, specify the PREC operand as 
follows: 

FMULT PI,DIAM,RESULT-CIRCUM,PREC=LLL 

The instruction multiplies PI by DIAM and stores the result in CIRCUM. The 
operand PREC = LLL says that PI, DIAM, and CIRCUM are all extended-precision 
floating-point numbers. 

If only one of the operands is a double-precision floating-point number, the PREC 
operand must reflect the precision. In the following example: 

FMULT BASEAREA, HEIGHT , RESULT=VOLUME , PREC=LFL 

the instruction multiplies BASEAREA by HEIGHT and stores the result in 
VOLUME. The operand PREC = LFL says that BASEAREA and VOLUME are 
extended-precision floating-point numbers and that HEIGHT is a single-precision 
floating-point number. 

Dividing Floating-Point Numbers 

The FDIVD instruction divides one floating-point number by another. The system 
stores the remainder in the first word of the task control block (TCB). 

If P and Q are single-precision floating-point numbers, you can divide P by Q as 
follows: 

FDIVD P,Q 

The result of the division replaces P. 

You can also divide a floating-point number by a constant. The following 
instruction divides FEET by the integer constant 3: 

FDIVD FEET, 3 

The result of the division replaces FEET. 

To divide two floating-point numbers without altering the first operand, use the 
RESULT operand as follows: 

FDIVD TOTWGT, BOXES, RESULT=BOXWGT 

The instruction divides TOTWGT by BOXES and stores the result in BOXWGT. 
The values in TOTWGT and BOXES do not change. 
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Dividing Extended-Precision Floating-Point Numbers: 

Unless you specify otherwise, EDL assumes that floating-point numbers are 
single-precision (2-word) floating-point numbers. To divide two extended-precision 
(4-word) floating-point numbers, specify the PREC operand as follows: 

FDIVD CUBICFT,BASEAREA,RESULT=HEIGHT,PREC=LLL 

The instruction divides CUBICFT by BASEAREA and stores the result in 
HEIGHT. The operand PREC = LLL says that CUBICFT, BASEAREA, and 
HEIGHT are all extended-precision floating-point numbers. 

If only one of the operands is an extended-precision floating-point number, the 
PREC operand must reflect the precision. In the following example: 

FDIVD TOTSAL,NOEMPS,RESULT=AVESAL,PREC=LFL 

the instruction divides TOTSAL by NOEMPS and stores the result in AVESAL. 
The operand PREC = LFL says that TOTSAL and AVESAL are extended-precision 
floating-point numbers and that NOEMPS is a single-precision floating-point 
number. 

Manipulating Logical Data 

The instructions that manipulate logical data make a bit-by-bit comparison of two 
bit strings. The result of the comparison depends on the instruction. 

The Exclusive-OR instruction 

The exclusive-OR instruction (EOR) compares two bit strings and produces a third 

bit string, called the resulting field. t 



The instruction compares the two bit strings one bit at a time. If the bits are the 
same, the instruction sets a bit in the resulting field to 0. If the bits are not the 
same, the instruction sets a bit in the resulting field to 1 . 

If the bit strings are identical, the resulting field contains all Os. If one or more bits 
differ, the resulting field contains a mixture of Os and Is. 

The following example compares PHI to CHI and stores the result in PHI. CHI 
remains unchanged. 

EOR PHI, CHI 
The following table shows PHI and CHI before and after the instruction executes. 
Data Item Hex Binary 

PHI (before) 049C 0000 0100 10011100 

CHI (before) 56AB 0101 0110 1010 1011 

PHI (after) 5237 0101 0010 0011 0111 
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Data Item Hex Binary 

CHI (after) 56AB 0101 0110 1010 1011 

To compare a variable to a constant, code operandi as follows: 
EGR MU,X'5280' 

The following table shows MU before and after the instruction executes. 

Data Item Hex Binary 

MU (before) FOFO 1111 0000 1111 0000 

constant 5280 0101 0010 1000 0000 

MU (after) A270 1010 0010 01110000 

To compare two bit strings without altering the first operand, use the RESULT 
operand as follows: 

EGR SIGMA, DELTA, RESULT=THETA 

The instruction compares SIGMA and DELTA and stores the resulting field in 
THETA. SIGMA and DELTA do not change. 

Unless you specify otherwise, EDL assumes that the bit strings you specify are 
one-word (2-byte) variables. To compare a single byte or more than two bytes, 
specify the number of consecutive units (bytes, words, or doublewords) that you 
want to compare. For example: 

EGR MASKl ,MASK2 , (3 , BYTE) , RESULT=MASK3 



MASKl DATA X'12A4E6' 
MASK2 DATA X'QIGI' 
MASKS DATA X'GOGOOG' 

The instruction compares three bytes at MASKl with the first byte at MASK2 and 
stores the result in MASK3. After the instruction executes in this example, MASK3 
contains X'13A5E7'. 

The Inciusive-OR Instruction 

The inclusive-OR instruction (lOR) compares two bit strings and produces a third 
bit string, called the resulting field. 

The instruction compares the two bit strings one bit at a time. If either or both bits 
are 1, the instruction sets a bit in the resulting field to 1. If neither bit is 1, the 
instruction sets a bit in the resulting field to 0. 
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The following example compares ETA to RHO and stores the result in ETA. RHO 
is unchanged. 

lOR ETA, RHO 

The following table shows ETA and R.HO before and after the instruction executes. 

Data Item Hex Binary 

ETA (before) 049C 0000 0100 10011100 

RHO (before) 56AB 0101 0110 1010 1011 

ETA (after) 56BF 01010110 10111111 

RHO (after) 56AB 0101 OHO 1010 1011 

To compare a variable to a constant, code operandi as follows: 
lOR XI,X'5280' 

The following table shows XI before and after the instruction executes. 

Data Item Hex Binary 

XI (before) FOFO 1111 0000 1111 0000 

constant 5280 0101 0010 1000 0000 ^f^ 

XI (after) F2F0 1 1 1 1 00 1 1 1 1 1 0000 



To compare two bit strings without altering the first operand, use the RESULT 
operand as follows: 

lOR 0PER1,0PER2,RESULT=TEST1 

The instruction compares OPERl and OPER2 and stores the resulting field in 
TESTl. OPERl and OPER2 do not change. 

Unless you specify otherwise, EDL assumes that the bit strings you specify are 
one-word (2-byte) variables. To compare a single byte or more than two bytes, 
specify the number of consecutive units (bytes, words, or doublewords) that you 
want to compare. For example: 

TOR MASK1,MASK2, (4,DW0RD) ,RESULT=MASK3 

The instruction compares the first doubleword at MASK2 with the four doublewords 
at MASKl and stores the resulting field in MASK3. 
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The AND Instruction 

The AND instruction (AND) compares two bit strings and produces a third bit 
string, called the resulting field. 

The instruction compares the two bit strings one bit at a time. If both bits are 1, the 
instruction sets a bit in the resulting field to 1 . If either or both bits are 0, the 
instruction sets a bit in the resulting field to 0. 

The following example compares BETA to THETA and stores the result in BETA. 
AND BETA, THETA 

The following table shows BETA both before and after the instruction executes. 

Data Item Hex Binary 

BETA (before) 049C 0000 0100 10011100 

THETA 56AB 0101 OHO 1010 1011 

BETA (after) 0488 0000 0100 1000 1000 

To compare a variable to a constant, code operandi as follows: 
AND LAMBDA,X'5280' 

The following table shows LAMBDA both before and after the instruction executes. 

Data Item Hex Binary 

LAMBDA FOFO 11110000 11110000 

(before) 

constant 5280 0101 0010 1000 0000 

LAMBDA 5080 0101 0000 1000 0000 

(after) 

To compare two bit strings without altering the first operand, use the RESULT 
operand as follows: 

AND 0PER1,0PER2,RESULT=TEST1 

The instruction compares OPERl and OPER2 and stores the resulting field in 
TESTl. OPERl and OPER2 do not change. 

Unless you specify otherwise, EDL assumes that the bit strings you specify are 
one-word (2-byte) variables. To compare a single byte or more than two bytes, 
specify the number of consecutive units (bytes, words, or doublewords) that you 
want to compare. For example: 

AND OPERl , 0PER2 , (2 , WORD) , RESULT=TEST1 

The instruction compares the first word at OPER2 with the two words at OPERl 
and stores the resulting field in TESTl. 
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Writing Data from a Data Area 



When you write data from a data area, the instruction you use depends on the kind 
of data and where you write it. 

To write data to disk, diskette, or tape, use the WRITE instruction. To v/rite data 
to a terminal, use either the PRINTEXT or PRINTNUM instruction. If the data is 
alphanumeric, use PRINTEXT. If the data consists of either one floating-point 
number or one or more integers, use PRINTNUM. 

Writing Data to Disk or Dislcette 

You can write disk or diskette data sets either sequentially or directly. You always 
write 256 bytes, an "EDX record." 

The following WRITE instruction writes a record sequentially: 
WRITE DS3,DISKBUFF,1,0,ERROR=WRITERR 



DISKBUFF BUFFER 256, BYTES 

The instruction writes a record to the third data set defined on the PROGRAM 

statement (DS3). The system writes one record (indicated by 1 in the third operand) 

sequentially (indicated by in the fourth operand) into DISKBUFF. If an I/O error 

occurs, the program branches to WRITERR. Otherwise, the system writes the 

256-byte buffer DISKBUFF to the data set. ^-^ 

The following WRITE instruction writes a record directly: 
WRITE DS5,BUFR,1, REGNO, ERROR=BADWRIT 



BUFR BUFFER 256, BYTES 
REGNO DATA F 

The instruction writes a record to the fifth data set defined on the PROGRAM 
statement (DS5). The system writes one record (indicated by 1 in the third operand) 
directly (indicated by the presence of the label REGNO in the fourth operand) into 
BUFR. The contents of REGNO indicate which record the system will write. For 
example, if REGNO contains 150, the system writes the 150th record. 

If an I/O error occurs, the program branches to BAD WRIT. Otherwise, the system 
writes BUFR to the data set. 
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Writing Data to Tape 

You can write tape data sets sequentially only. A tape WRITE writes a record from 
18 to 32767 bytes long. 

The following WRITE instruction writes a record to a tape: 
WRITE DSl, BUFF, 1, 328, ERROR=ERR,WAIT=YES 



BUFF BUFFER 328, BYTES 

The system writes one record (indicated by 1 in the third operand). The size of the 
record is 328 bytes (indicated by 328 in the fourth operand). If an error occurs, 
control transfers to ERR. The system waits for the write operation to complete 
before continuing execution (WAIT = YES). 

The following WRITE instruction writes two records from buffer BUFF2: 
WRITE DS1,BUFF2,2,328,ERR0R=ERR,WAIT=YES 



BUFF2 BUFFER 656, BYTES 

The system writes two records (indicated by 2 in the third operand). The size of 
each record is 328 bytes (indicated by 328 in the fourth operand). If an error occurs, 
control transfers to ERR. The system waits for the operation to complete before 
continuing (WAIT = YES). 

Writing to a Terminal 

Two of the instructions that write data to a terminal are the PRINTEXT and 
PRINTNUM instructions. The PRINTEXT instruction allows you to write 
alphanumeric data (alphabetic characters, numbers, and special characters). With 
the PRINTNUM instruction, you can write numbers (both integer and 
floating-point) only. 

Writing Alphanumeric Data 

To write alphanumeric data to a terminal, use the PRINTEXT instruction as 
follows: 

PRINTEXT DESC,SKIP=3 



DESC TEXT "NOW IS THE TIME FOR ALL GOOD MEN' 

The instruction writes (or displays) the 25 alphanumeric characters in DESC. The 
operand SKIP = 3 causes the system to skip three lines before displaying DESC. 

For information on writing alphanumeric data to screens, see Chapter 8, "Reading 
Data from and Writing to Screens." 
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Writing Numeric Data 

The PRINTNUM iiistruction allows you to write either a single floating-point value 
or more than one integer to a terminal. The following instruction writes a 
floating-point number: 

PRINTNUM BASAL,TYPE=F,F0RMAT=(6,2,F) 

The instruction writes the number contained in the variable BASAL. The operand 
TYPE = F means that BASAL is a single-precision floating-point number. The 
operand FORMAT = (6,2,F) tells the system to display the number in 6 positions on 
the screen (including the decimal point), to display 2 digits to the right of the 
decimal point, and to display it as an "F-type" number such as 436.32. 

To write more than one integer, code a second operand on the instruction as follows: 
PRINTNUM WEIGHTS,? 

The instruction displays the 7 one-word values starting at location WEIGHTS. The 
instruction assumes that you have defined WEIGHTS as follows: 

WEIGHTS DATA 7F'0' 



o 



Controlling Program Logic 



This section discusses the EDL instructions used to control the logic or execution of 
instructions. The following instructions are the primary means of controlling 
program logic: 

DO— initializes a loop 

ENDDO-ends a loop 

IF— tests a condition 

ELSE— specifies the action for a false condition 

ENDIF— €nds an IF-ELSE structure 

GOTO— branches to another location. 






Relational Operators 

The IF and DO statements involve the use of the following relational operators: 
EQ— equal 
NE— not equal 
GT— greater than 
LT— less than 
GE— greater than or equal 
LE— less than or equal. 
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The IF Instruction 

The IF instruction allows you to compare two areas of storage. You can compare 
data in two ways: arithmetically or logically. 

When you compare data arithmetically, the system interprets each number as a 
positive or negative value. The system, for example, interprets X ' OFFF ' as 4095. It 
interprets X'FFFD', however, as -3. Although X'FFFD' seems to be a larger 
hexadecimal number than X ' OFFF ' , the system recognizes X ' FFFD ' as a negative 
number and X ' OFFF ' as a positive number. X ' FFFD ' is a negative number to the 
system because the leftmost bit is "on." 

When you compare data logically, the system compares the data byte-by-byte. The 
system interprets X'FFFF' as 2 bytes with all bits "on." 

Comparing Data Arithmetically 

The form of the arithmetic comparison is: 
IF (datal, operator, data2, width) 

If datal has the relationship indicated by operator to data2, the next sequential 
Instruction executes. Width indicates the length of the data to be compared and 
must be BYTE, WORD (the default), DWORD, FLOAT, or DFLOAT. 

The true portion of the IF-ELSE-ENDIF structure is usually an arithmetic 
comparison. For example: 

IF (A,EQ,B,WORD) 

PRINTNUM A 
ELSE 

PRINTNUM B 
ENDIF 

ELSE is an optional part of the structure. The instructions following it are called the 
false part of the structure. Therefore, in the preceding example, the instruction 
following the ELSE instruction executes if A is not equal to B. If ELSE is not 
coded and the condition is false, control passes to the instruction following the 
ENDIF. 

You can test more than two conditions in a single IF statement. 
IF (ALPHA,LT,BETA) , AND, (GAMMA, NE, DELTA) 

If ALPHA is less than BETA and GAMMA is not equal to DELTA, the next 
sequential instruction executes. 

You can also execute the next sequential instruction if either test produces a true 
condition. 

IF (PI,GE,PSI),OR,(CHI,NE,OMEGA) 

If PI is greater than or equal to PSI or CHI is not equal to OMEGA, the next 
sequential instruction executes. 
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To compare a variable to a constant, code the constant as data2 as follows: 

IF (FEET, EQ, 5280) ^~\ 

If FEET equals 5280 (decimal), the next sequential instruction executes. 

CcmparsRg Data Lcgscally 

The form of the logical comparison is: 
IF (datal, operator, dataZ, width) 

If datal has the relationship indicated by operator to data2, the next sequential 
instruction executes. Width indicates the number of bytes to be compared and must 
be an integer. 

For example: 

IF (A,GE,B,4) 

PRINTNUM A 

PRINTEXT SKIP=1 
ELSE 

PRINTNUM B 

PRINTEXT SKIP=1 
ENDIF 

If the 4 bytes in A are greater than or equal to the 4 bytes in B, the "true" portion 
of the structure executes. If the 4 bytes in A are not greater than or equal to the 4 
bytes in B, the "false" portion of the structure executes. 

The instructions between the IF instruction and the ELSE statement constitute the 
"true" portion of the IF-ELSE-ENDIF structure. The instructions following the 
ELSE statement constitute the "false" part of the structure. ELSE is an optional 
part of the structure. 

If the ELSE instruction is not coded and the condition is false, control passes to the 
instruction following the ENDIF. 

The Program Loop 

The DO instruction allows you to execute the same code repetitively. The DO 
instruction starts a DO loop and the ENDDO instruction ends the loop. The loop 
consists of the instructions between the DO and ENDDO. The following sections 
show the different forms of the DO loop. 






The Simple DO 



The loop executes a specified number of times. 

DO 100, TIMES 

GETVALUE PSI, PROMPTS 

ADD COUNT, PSI 
ENDDO 



The GETVALUE and ADD instructions execute 100 times. 
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The DO UNTIL 



The loop executes until the condition occurs. The loop always executes at least once 
and is known as a "trailing" decision loop. 

DO UNTIL, (CDED,GT,1G0G, FLOAT) 

GETVALUE OMICRON,OMPRMPT 

FSUB CDED,OMICRGN 

ENDDO 

The GETVALUE and FSUB instructions execute until CDED is greater than 1000. 



The DO WHILE 



The loop executes as long as the condition exists and is know as a "leading" decision 
loop. 

DO WHILE, (B,NE,C) 

GETVALUE B,' ENTER B' 

GETVALUE C,' ENTER C' 
ENDDO 



The GETVALUE instructions execute as long as B does not equal C. 



The Nested DO Loop 






A DO loop can contain other DO loops. For example: 

DO UNTIL, (ALPHA, LT, BETA, DFLOAT), OR, (#1,EQ, 1000) 
GETVALUE ALPHA, 'ENTER ALPHA' ,TYPE=L,F0RMAT=(12,3,E) 
GETVALUE BETA, 'ENTER BETA' ,TYPE=L,FORMAT=( 12,3, E) 
MOVE #1, BETA, (1, DFLOAT) 
DO 10, TIMES 

FADD GAMMA, ALPHA, PREC=LLL 
ENDDO 

ENDDO 

The FADD statement contained in the inner DO executes 10 times for each 
execution of the outer DO. 
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The Nested IF instruction 

A DO loop can also contain IF statements. For example: 

READTEXT CHAR, 'ENTER A CHARACTER' 
GETVALUE A, 'ENTER A' 
GETVALUE B,' ENTER B' 
DO WHILE,(A,GT,B) 

IF (CHAR, EQ,C'A', BYTE) 
DO 40, TIMES 



ENDDO 
ELSE 



ENDIF 

GETVALUE A, 'ENTER A' 
GETVALUE B,' ENTER B' 
ENDDO 

The outer DO loop executes as long as A is greater than B. The inner DO loop 
executes 40 times if CHAR equals the letter A. 

Branching to Another Location 

The GOTO instruction allows you to transfer control to another location within a 

program. For example, the following instruction transfers control to the instruction ,iC"^' 

at label LOCI: \^ 

GOTO LOCI 

To branch to an address defined by a label, enclose the label in parentheses as 
follows: 

GOTO (CALC) 

This instruction branches to the address contained in CALC. You must define 
CALC as an address variable as in the following DATA statement: 

CALC DATA A(RTNOl) 

To branch to a location that is based on the contents of a variable, code the GOTO 
statement hke this: 

GOTO (ERR, LI, L2), I 

The instruction branches to LI if I equals 1, to L2 if I equals 2, and to ERR for any 
other value of L 
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Referring to a Storage (Program) Location 

You can use the EQU statement to refer to the next available storage location in a 
program. You can use it to generate labels in your program. For example: 

CALLA EQU * 

MOVE C,+A,(1,BYTE) 



GOTO CALLA 

Ending the Program 

Ending a program requires three statements: PROGSTOP, ENDPROG, and END. 

The PROGSTOP statement ends the program and releases any storage that it used. 
It also signals the end of the executable instructions. 

The ENDPROG statement follows the statements that define storage areas and 
precedes the END statement. 

The END statement follows the ENDPROG statement. It tells the compiler that the 
program contains no more statements. 

The following example shows the position of the three statements and the general 
structure of a program. 

PRINT PROGRAM START 
START EQU * 



PROGSTOP 
FIELDl DATA F'O' 



ENDPROG 
END 
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Chapter 3. Entering a Source Program 



After you code a source program, you must enter it into a data set. The data set 
can be on either disk, diskette, or tape. 

This chapter shows how to use the text editor called the SFSEDIT utility. The 
chapter describes the commands you need to enter a new source program or change 
an existing source program. For a complete list of SFSEDIT commands, refer to the 
Operator Commands and Utilities Reference. 



Loading the Editor 



You can load the editor in one of two ways. You can load it directly using the $L 
command. Or, you can load it using the session manager. 

This chapter discusses how to load the editor with the session manager. For 
information on how to load SFSEDIT with the $L command, refer to the Operator 
Commands and Utilities Reference. 






As you learned in Chapter 1 of this book, you load the session manager by pressing 
the attention key, typing $L $SMMAIN, and pressing the enter key. 

At this point, enter a one- to four-character ID and press the enter key. 

The Session Manager Primary Option Menu appears. From this menu, select option 
1 (TEXT EDITING). 



$SMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



PRESS PF3 TO EXIT 
06:09:00 



SELECT OPTION ==> 1 



09/23/84 



ABCD 



10 



TEXT EDITING 
PROGRAM PREPARATION 
DATA MANAGEMENT 
TERMINAL UTILITIES 
GRAPHICS UTILITIES 
EXEC PROGRAM/UTILITY 

7 - EXEC $JOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTIC AIDS 
BACKGROUND JOB CONTROL UTILITIES 



The session manager displays the SFSEDIT Primary Option Menu. 
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Creating a New Data Set 



The session manager allocates data sets automatically when you log on. One of 
these data sets, a work data set used by SFSEDIT, is named $SMExxxx, where xxxx 
is the ID you entered when you logged on to the session manager. For example, if 
you entered ABCD when you logged on, the work data set is SSMEABCD. 

Use option 2 (EDIT) to type your source program into the work data set. 



$FSEDIT PRIMARY OPTION MENU - - -STATUS = INIT 

PRESS PF3 TO EXIT 
OPTION ===> 2 



DATASET NAME 
VOLUME NAME = 



(CURRENTLY IN WORK FILE) 



HOST DATASET ========> 

ENTER A VOLUME NAME AND PRESS ENTER FOR A DIRECTORY LIST. 

1 BROWSE 

2 EDIT 

3 — - READ (HOST/NATIVE) 

4 WRITE (HOST/NATIVE) 

5 SUBMIT 

6 PRINT 

7 MERGE 

8 — - END 

9 HELP 






An empty data set appears on your screen. The name of the data set and the 
volume on which it resides are shown at the top of the screen. 



EDIT — SSMEABCD, EDXO03 0(1089) COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 

***** ***** TQP OP DATA ******************************************************* 



***** **** RQTTOM OF DATA ***************************************************** 



The cursor is located at the first input line. After you finish typing text on this Une, 
press the enter key. 



o 
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The following example shows how the screen looks after you enter the first hne of a 
source program. (We have used the source program described in Chapter 1 of this 
book.) The editor automatically numbers each line and presents a new blank line. 



EDIT — $SMEABCD, EDX003 0(1089) - COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 

***** ***** TQP OF DATA ******************************************************* 

00010 ADD10 PROGRAM STPGM 



***** **** BOTTOM OF DATA ***************************************************** 



Continue to type each line of your source program. When you finish, press the enter 
key on a blank line. 






EDIT — $SMEABCD , EDX003 12( 1089) COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 

***** ***** TQP OF DATA ******************************************************* 

+00010 ADD10 PROGRAM STPGM 
+00020 STPGM GETVALUE COUNT, "ENTER NUMBER: ' 
+00030 LOOP 
+00040 
+00050 
+00060 
+00070 
+00080 
+00090 COUNT 
+00100 SUM 
+00110 
+00120 
***** ***** RoyTOM OF DATA *****************************^********************** 



DO 


10, TIMES 


ADD 


SUM, COUNT 


ENDDO 




PRINTEXT 


'0RESULT=' 


PRINTNUM 


SUM 


PROGSTOP 




DATA 


F'O' 


DATA 


F'0' 


ENDPROG 




END 
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Saving Your Data Set 



The next step is to save your data set. Return to the SFSEDIT Primary Option 
Menu by typing M (for "menu") on the COMMAND INPUT Hne. 

Select option 4 (WRITE) to save the data set. Type the name next on the 
DATASET NAME Hne. (In this example, we named the data set ADD 10.) Type 
the volume on the VOLUME NAME hne. (In this example, the volume is 
EDX002.) Then press the enter key. 



$FSEDIT PRIMARY OPTION MENU STATUS = MODIFIED 

PRESS PF3 TO EXIT 
OPTION ===> 4 

DATASET NAME =========> ADDIO (CURRENTLY IN WORK FILE) 

VOLUME NAME ==========> EDX0G2 

HOST DATASET ========> 

ENTER A VOLUME NAME AND PRESS ENTER FOR A DIRECTORY LIST. 

1 BROWSE 

2 — - EDIT 

3 READ (HOST/NATIVE) 

4 WRITE (HOST/NATIVE) 

5 SUBMIT 

6 PRINT 

7 MERGE 

8 END 

9 HELP 



Next, the system prompts you as follows: 



WRITE TO ADDIO ON EDXO02 (Y/N)' 



Type Y and press the enter key. 

Then you see a message on your screen indicating that the data set has been written 
to the volume. In the example shown above, the following message would appear: 



12 LINES WRITTEN TO ADDIO, EDX0O2 



This message means that the source program is 12 records long and has been written 
to volume EDX002. 



kJ 
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Modifying an Existing Data Set 



You have seen how to enter a source program into a new data set. You can also 
modify an existing data set. 

You must first read the data set you want to modify into the work data set. Select 
option 3 (READ) from the SFSEDIT Primary Options Menu. On the menu, you 
specify which data set you want to read. 

Next, you select option 2 (EDIT) to modify the data set. 

The data set appears on your screen. 



r 






EDIT — ADDIQ , EDX0O2 12( 1089) -- COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 

***** ***** TQp OF DATA ******************************************************* 



00010 ADDIO 


PROGRAM 


STPGM 


00020 STPGM 


GETVALUE 


COUNT, 'ENTER NUMBER: 


00030 LOOP 


DO 


lOJIMES 


00040 


ADD 


SUM, COUNT 


00050 


ENDDO 




00060 


PRINTEXT 


'0RESULT=' 


00070 


PRINTNUM 


SUM 


00080 


PROGSTOP 




00090 COUNT 


DATA 


F'O' 


00100 SUM 


DATA 


F'O' 


00110 


ENDPROG 




00120 


END 





***** ***** BOTTOM OF DATA **************************************************** 



Changing a Line 



To change a line, move the cursor to the Une and type in the correction. For 
example, suppose you wanted to change 10 to 15 in the DO instruction. Move the 
cursor to the and type a 5. 

Or, suppose you wanted to delete the = character in the PRINTEXT instruction. 
Move the cursor to the = character and press the delete key. 
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Inserting a Line 



You can insert a new line into your data set. You insert a line by typing an I in the 
line number after which you want to insert. 

For example, suppose you want to insert another instruction before PROGSTOP. 
Type the I as follows: 



EDIT — ADD10 , EDX002 12( 1089) -- — COLUMNS 001 072 

COMMAND INPUT ===> _ SCROLL ==> HALF 

***** ***** Tnp OF DATA ******************************************************* 

00010 ADD10 PROGRAM STP6M 



00020 STPGM 


GETVALUE 


COUNT, 'ENT 


00030 LOOP 


DO 


10, TIMES 


00040 


ADD 


SUM, COUNT 


00050 


ENDD0 




00060 


PRINTEXT 


'(3RESULT=' 


10070 


PRINTNUM 


SUM 


00080 


PROGSTOP 




00090 COUNT 


DATA 


F'O' 


00100 SUM 


DATA 


F'O' 


00110 


ENDPROG 




00120 


END 





***** ***** ROTTOM OF DATA **************************************************** 



After you press the enter key, your data set looks hke this: 



EDIT — ADDIO , EDXO02 12( 1089)-- - COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 

***** ***** TQp Qp QATA ******************************************************* 

00010 ADD10 PROGRAM STPGM 



00020 STPGM 


GETVALUE 


COUNT, 'ENT 


00030 


LOOP 


DO 


10, TIMES 


00040 




ADD 


SUM, COUNT 


00050 




ENDOO 




00060 




PRINTEXT 


'@RESULT=' 


00070 




PRINTNUM 


SUM 


00080 




PROGSTOP 




00090 COUNT 


DATA 


F'O' 


00100 


SUM 


DATA 


F'O' 


00110 




ENDPROG 




00120 




END 




***** 


***** 


BOTTOM OF DATA ***************** 



You could now enter your new line of text at the position of the cursor. After you 
press enter, the editor assigns a line number to your new line of text. A new blank 
input hne also appears. You can continue to insert Hues or you can press the enter 
key again to indicate that you ha-ve finished inserting. 
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Deleting a Line 



You can delete a line or series of lines from your data set. 



%ijr 



To delete a single line, enter a D in the line number you want deleted and press the 
enter key. 



EDIT — ADDIO , EDX002 13{ 1089) COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 

ickicieic ie-kicick THP OF DATA ****"********************************■******************* 

OGOIO ADDIO PROGRAM STPGM 

00020 STPGM GETVALUE COUNT, 'ENTER NUMBER: ' 

00030 LOOP DO 10, TIMES 

00040 ADD SUM, COUNT 

00050 ENDDO 

00060 PRINTEXT '@RESULT=' 

00070 PRINTNUM SUM 

D008O *********npl ets this ling********************** 

00090 PROGSTOP 

00100 COUNT DATA F'O' 

00110 SUM DATA F'O' 

00120 ENDPROG 

00130 END 

***** ***** RnTTOM OF DATA **************************************************** 



After you press the enter key, the editor deletes the Hne. 



COMMAND INPUT == 


==> 






***** ***** jgp 


OF 


DATA *************************************** 


00010 ADDIO 




PROGRAM 


STPGM 


00020 STPGM 




GETVALUE 


COUNT, 'ENTER NUMBER: ' 


00030 LOOP 




DO 


10, TIMES 


00040 




ADD 


SUM, COUNT 


00050 




ENDDO 




00060 




PRINTEXT 


'@RESULT=' 


00070 




PRINTNUM 


SUM 


00090 




PROGSTOP 




00100 COUNT 




DATA 


F'O' 


00110 SUM 




DATA 


F'O' 


00120 




ENDPROG 





COLUMNS 001 072 
SCROLL ==> HALF 



00130 END 

***** ***** RnTTHM OF DATA **************************************************** 
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You can also delete more than one line. 

For example, suppose you want to delete lines 80 through 120 in the following 
program. Type DD in line 80 and another DD in line 120. 



EDIT --- ADDIO , EDX0Q? 17( 1089)--- COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 

***** ***** TQp gp QATA ******************************************************* 

00010 ADDIO PROGRAM STPGM 

00020 STPGM GETVALUE COUNT, 'ENTER NUMBER: ' 

00030 LOOP DO 10, TIMES 

00040 ADD SUM, COUNT 

00050 ENDDO 

00060 PRINTEXT '@RESULT=' 

00070 PRINTNUM SUM 

DDO80 **********Dp1 ete thess "lines********************* 

00090 ****** ****** 

00100 ****** ****** 

00110 ****** ****** 

DD120 **********r)p] p+p thPSG i ippc********************* 

00130 PROGSTOP 

00140 COUNT DATA F'O' 

00150 SUM DATA F'O' 

00160 ENDPROG 

00170 END 

***** ***** RQTTQM OF DATA **************************************************** 



After you press the enter key, your program looks Hke this: 



EDIT — ADDIO 
COMMAND INPUT ===> 


, EDXO02 


i?r lOftQ^ rni UMNS ooi 072 


SCROLL ==> HALF 


***** 


***** 


TOP OF 


DATA ******************************************************* 


00010 ADDIO 




PROGRAM 


STPGM 


00020 


STPGM 




GETVALUE 


COUNT, 'ENTER NUMBER: ' 


00030 


LOOP 




DO 


10. TIMES 


00040 






ADD 


SUM, COUNT 


00050 






ENDDO 




00060 






PRINTEXT 


'?RESULT=' 


00070 






PRINTNUM 


SUM 


00130 






PROGSTOP 




00140 


COUNT 




DATA 


F'O' 


00150 


SUM 




DATA 


F'O' 


00160 






ENDPROG 




00170 






END 




***** 


***** 


BOTTOM 


OF DATA **************************************************** 



The editor deletes the lines. 
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Moving Lines 



You can move a line or series of lines from one part of your data set to another. 
For example, suppose you want to move lines 110 through 130. First type MM in 
both 1 10 and 130. If you want to move these lines after Une 10, place an A (for 
"after") on Une 10 and press the enter key. 



EDIT — ADDIO . EDX0O2 15( 1089) COLUMNS 001 072 

COMMAND INPUT ===> SCROLL ==> HALF 

***** ***** TQp Qp QATA ******************************************************* 

A0O1O ADD10 PROGRAM STPGM 

COUNT, 'ENTER NUMBER: ' 

lO.TIMES 

SUM, COUNT 



00020 STPGM 
00030 LOOP 
00040 
00050 
00060 
00070 
00080 

00090 COUNT 
00100 SUM 



6ETVALUE 

DO 
ADD 

ENDDO 

PRINTEXT '@RESULT=' 

PRINTNUM SUM 

PROGSTOP 

DATA F'O' 

DATA F'O' 
mmIIO *********Move these ]ipg5*********************** 
00120 ***** ***** 

mm130 *********Move these lines*********************** 
00140 ENDPROG 

00150 END 

***** ***** ROTTOM OF DATA **************************************************** 






When you press the enter key, the editor moves the Hnes to the position after line 10. 



EDIT — ADD10 , EDX002 15( 1089) -- COLUMNS 001 072 

COMMAND INPUT ===> " SCROLL ==> HALF 

***** ***** TQP QC nATA ******************************************************* 

00010 ADDIO PROGRAM STPGM 

+00020 *********Move these lines*********************** 
+00030 ***** ***** 

+00040 *********Move these lines*********************** 
00050 STPGM 
00060 LOOP 
00070 
00080 
00090 
00100 
00110 

00120 COUNT 
00130 SUM 
00140 
00150 

***** ***** BOTTOM OF DATA **************************************************** j 
V J 



GETVALUE 


COUNT, 'ENTER NUMBER 


DO 


10, TIMES 


ADD 


SUM, COUNT 


ENDDO 




PRINTEXT 


'@RESULT=' 


PRINTNUM 


SUM 


PROGSTOP 




DATA 


F'O' 


DATA 


F'O' 


ENDPROG 




END 





After you make changes to your data set, return to the $FSEDIT Primary Options 
Menu. Return to that menu by typing M (for "menu") on the COMMAND INPUT 
hne. To save the changes, select option 4 and press the enter key. 

You have seen how you can change lines in your programs. You have also seen how 
to insert and delete Hnes and move a series of hnes. The session manager was used 
to load SFSEDIT and to allocate the necessary data sets. The next chapter explains 
how to compile your programs using SEDXASM, the EDX compiler. 
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Chapter 4. Compiling a Program 



After you design, code, and enter your source program into a data set, you have to 
compile the source program into an object module. This chapter shows you how to 
compile your source program using the Event Driven Language Compiler, 
$EDXASM. 

The chapter also shows a step-by-step example of compiling a source program that 
contains some syntax errors. The chapter then shows how to correct the errors so 
that the compilation is successful. 

You can load $EDXASM in one of three ways. You can load $EDXASM directly 
using the $L command. You can use the SJOBUTIL utihty to load $EDXASM. 
Or, you can run your compilation under control of the session manager. 

This chapter describes how to compile a program using the session manager. 

For information on using the $L command or the SJOBUTIL utility, refer to the 
Operator Commands and Utilities Reference. 



Allocating Data Sets 



m|||„..j>^'' 



When you use SEDXASM under control of the session manager, you must provide 
two data sets. The first data set is the actual source program to be compiled. You 
must have entered the source program on a disk, diskette, or tape data set. 
Chapter 3, "Entering a Source Program" describes how to use the SFSEDIT utihty 
to enter your source programs. 

The output of the compiler is a data set that contains an object module. You can 
allocate this data set by selecting option 3 (DATA MANAGEMENT) from the 
Session Manager Primary Option Menu. 



5SMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



SELECT OPTION ==> 3 



PRESS PF3 TO EXIT 



19:42:07 
10/24/82 
ABCD 



1 - TEXT EDITING 

2 - PROGRAM PREPARATION 

3 - DATA MANAGEMENT 

4 - TERMINAL UTILITIES 

5 - GRAPHICS UTILITIES 

6 - EXEC PROGRAM/UTILITY 

7 - EXEC SJOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTIC AIDS 

10 - BACKGROUND JOB CONTROL UTILITIES 



Note: This example assumes that you logged on to the Session Manager with an ID 
of ABCD. 
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The Data Management Option Menu appears on the screen, 
code data set, select option 1 (SDISKUTl). 



To allocate your object 



r~ 



$SMM03 SESSION MANAGER DATA MANAGEMENT OPTION MENU- 

CMTCp/CCICrT DApAMCTITDC. 



SELECT OPTION ==> 1 



PRESS PF3 TO RETURN 



1 - $DISKUT1 



$DISKUT2 

SCOPYUTl 

$COMPRES 

SCOPY 

$DASDI 

SINITDSK 



8 - $MOVEVOL 

9 - $IAMUT1 

10 - STAPEUTl 

11 - $HXUT1 

12 - $INSTAL 



DISK(ETTE) ALLOCATE, LIST DIRECTORY) 
DISK(ETTE) DUMP/LIST DATASETS) 
DISK(ETTE) COPY DATASETS/VOLUMES) 
DISK(ETTE) COMPRESS A VOLUME) 
DISK(ETTE) COPY DATASETS/VOLUMES) 
DISK(ETTE) SURFACE INITIALIZATION) 
DISK(ETTE) INITIALIZE/VERIFY) 
COPY DISK VOLUME TO MULTI-DISKETTES) 
INDEXED ACCESS METHOD UTILITY PROGRAM) 
TAPE ALLOCATE, CHANGE, COPY) 
H-EXCHANGE DATASET UTILITY) 
INSTALL/UPDATE A SOFTWARE PACKAGE) 



WHEN ENTERING THESE UTILITIES, THE USER IS EXPECTED 
TO ENTER A COMMAND. IF A QUESTION MARK (?) IS ENTERED 
INSTEAD OF A COMMAND, THE USER WILL BE PRESENTED WITH 
A LIST OF AVAILABLE COMMANDS. 



The session manager loads the SDISKUTl utility and prompts for the command you 
want to use. 



LOADING SDISKUTl nnP, hh:mm:ss, LP= xxxx, PART= yy 
$DISKUT1 - DATA SET MANAGEMENT UTILITY I 
USING VOLUME EDX002 
COMMAND (?): 






Notice the USING VOLUME EDX002 message. Unless you change volumes, 
SDISKUTl allocates your data set on EDX002. 
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When you do not want to use the default volume, change the default volume to 
MYVOL, using the following CV command: 



USING VOLUME EDX0O2 
COMMAND (?): CV MYVOL 

The system responds with: 

USING VOLUME MYVOL 
COMMAND (?): _ 



Use the AL command to allocate your data set. 



COMMAND (?): AL 
MEMBER NAME: 



^r**^,^ 
^\^jii-^ 



The system then prompts you for the name of the data set. In this example, the data 
set name is OBJECT. 



MEMBER NAME: OBJECT 
HOW MANY RECORDS? 



Next, the system prompts for the number of records you want to allocate. A 25- to 
50-record data set should be large enough for most programs. This example defines 
a 25-record data set. 



HOW MANY RECORDS? 25 

DEFAULT TYPE = DATA - OK(Y/N)? _ 
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Finally, the system prompts for the type of information to be contained in the data 
set. The default is DATA. Because this data set will contain data, enter a Y. 



The system responds with: 



OBJECT CREATED 
COMMAND (?): 



y 



Once the data set has been created, enter an EN (for "end") to return to the Data 
Management Option Menu screen. 



COMMAND (?): EN 
SDISKUTl ENDED 08:30:24 



Return to the Session Manager Primary Option Menu to begin the compilation by 
pressing the PF3 key. 






Running the Compilation 



Once you have allocated the data set to hold the output, you are ready to begin 
compihng the source program. The following is a hsting of the source program to 
be compiled: 





PROGRAM 


STPGM 


STPGM 


GETVALUE 


COUNT, 'ENTER NUMBER 


LOOP 


DO 


10, TIMES 




ADD 


SUM, COUNT 




ENDDO 






PRINTEXT 


'RESULT=' 




PRINTNUM 


SUM 




PROGSTOP 




COUNT 


DATA 


F'O' 


SUM 


DATA 

ENDPROG 

END 


F'O' 



This program is similar to the examples we used in Chapter 1 and Chapter 3 of this 
book. However, we have included two errors in this source program. 



1^ 
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From the Session Manager Primary Option Menu, select option 2 (PROGRAM 
PREPARATION) to begin the compile step. 



$SMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



PRESS PF3 TO EXIT 



SELECT OPTION ==> 2 



19:48:07 
10/24/82 
ABGD 



10 - 



TEXT EDITING 

PROGRAM PREPARATION 

DATA MANAGEMENT 

TERMINAL UTILITIES 

GRAPHICS UTILITIES 

EXEC PROGRAM/UTILITY 

EXEC $JOBUTIL PROC 

COMMUNICATION UTILITIES 

DIAGNOSTIC AIDS 

BACKGROUND JOB CONTROL UTILITIES 



The Program Preparation Option Menu appears on your screen. To compile the 
program, select option 1 ($EDXASM COMPILER). 



$SMM02 SESSION MANAGER PROGRAM PREPARATION OPTION MENU- 
ENTER/SELECT PARAMETERS: 

SELECT OPTION ==> 1 



PRESS PF3 TO RETURN 



1 - $EDXASM COMPILER 

2 - $EDXASM/$EDXLINK 

3 - $S1ASM ASSEMBLER 

4 - $COBOL COMPILER 

5 - $FORT FORTRAN COMPILER 

6 - $PLI COMPILER/$EDXLINK 

7 - $EDXLINK LINKAGE EDITOR 

8 - $XPSLINK LINKAGE EDITOR FOR SUPERVISORS 

9 - SUPDATE 

IG - $UPDATEH (HOST) 

11 - $PREFIND 

12 - $PASCAL COMPILER/$EOXLINK 

13 - $EDXASM/$XPSLINK FOR SUPERVISORS 

14 - $MSGUT1 MESSAGE SOURCE PROCESSING UTILITY 



The SEDXASM Parameter Input Menu appears on your screen. Enter the name of 
your source input (in this example, ADDIO on volume EDX002). Also enter the 
name of your object output (in this example, data set OBJECT on volume 
MYVOL). 



C3 
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You could enter something on the OPTIONAL PARAMETERS line if you want to 
change one of the parameters listed on the DEFAULT PARAMETERS line. In this 
example, we are using the defaults. 



\mmJ^ 



$SMM0201: SESSION MANAGER $EDXASM PARAMETER INPUT MENU- 
ENTER/SELECT PARAMETERS: 



SOURCE INPUT (NAME, VOLUME) ==> ADD10,EDX9G2 

OBJECT OUTPUT (NAME, VOLUME) ==> OBJECT, MYVOL 

OPTIONAL PARAMETERS ==> 
(SELECT FROM THE LIST BELOW) 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 



PRESS PF3 TO RETURN 



AVAILABLE PARAMETERS: 
NOLIST 

LIST TERMINAL-NAME 
ERRORS TERMINAL-NAME 
CONTROL DATA SET, VOLUME 
OVERLAY # 



ABBREVIATION: 
NO 

LI TERMINAL-NAME 
ER TERMINAL-NAME 
CO DATA SET, VOLUME 
OV # 



DESCRIPTION: 
USED TO SUPPRESS LISTING 
USE LIST * FOR THIS TERMINAL 
USE ERRORS * FOR THIS TERMINAL 
SEDXASM LANGUAGE CONTROL DATASET 
# IS NUMBER OF AREAS FROM 1 TO 6 



DEFAULT PARAMETERS: 
LIST SSYSPRTR CONTROL $EDXL,ASMLIB OVERLAY 6 



v> 
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Checking Your Compiler Listing and Correcting Errors 

The output of the compiler prints on your printer. The Usting consists of statistics, 
source code statements and object code, undefined or external symbols, and a 
completion code. 

The following is an example of the output Hsting generated by the compile example 
being run, 

EDX ASSEMBLER STATISTICS 

SOURCE INPUT - ADD10.EDX0G2 
WORK DATA SET - WORKl.MYVOL 
OBJECT MODULE - OBJECT. MYVOL 
DATE: 10/24/82 AT 19:56:18 
ASSEMBLY TIME: 4 SECONDS 

STATEMENTS PROCESSED - 12 



LOC 



4 STATEMENTS FLAGGED 

PAGE 1 
+0 +2 +4 +6 +8 SOURCE STATEMENT ADD10 ,EDXO02 (5719 



PROGRAM 

08 *** TASK NAME NOT SPECIFIED 
0000 802C 0000 OO0A 0001 OEOE STPGM GETVALUE 
OOGA C5D5 E3C5 D940 D5E4 D4C2 
0014 C5D5 7A40 

08 *** ONE OR MORE UNDEFINED LABELS WERE REFERENCED 
0018 809C 0024 OOOA LOOP DO 

OOIE 0032 0040 0000 ADD 

08 *** ONE OR MORE UNDEFINED LABELS WERE REFERENCED 
0024 O09D 0000 0001 ENDDO 

0O2A 8026 0808 D9C5 E2E4 D3E3 PRINTEXT 

0034 7E40 PRINTNUM 

003C 0022 FFFF PROGSTOP 

COUNT DATA 

08 *** INVALID OR UNDEFINED OPERATION CODE 
0040 0000 SUM DATA 

0042 ENDPROG 

0042 END 



STPGM 

$EDXL 
COUNT, 'ENTER NUMBER: 



12 



10, TIMES 
SUM, COUNT 



'RESULT=' 
SUM 



$EDXL 



$EDXL 



F'0' 



F'O' 



$EDXL 11 






EXTERNAL/UNDEFINED SYMBOLS 
COUNT UNDEFINED 



COMPLETION CODE 



This example shows that the compile did not run successfully. The completion code 
expected is a — 1. The completion code received is an 8. 
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The listing shows the compilation errors. They are: 

• 08 *** TASK NAME NOT SPECIFIED 

• 08 *** ONE OR MORE UNDEFINED LABELS WERE REFERENCED 

• 08 *** INVALID OR UNDEFINED OPERATION CODE 



o 



To fix these errors, you must understand what caused them. Look the errors up in 
Messages and Codes. 

The first message, 08 *** TASK NAME NOT SPECIFIED, is a result of not having 
a task name coded on the PROGRAM statement. 

The second message, 08 *** ONE OR MORE UNDEFINED LABELS WERE 
REFERENCED, means that one of the labels referenced in the instruction has not 
been defined to the program. If you check the Hsting for undefined symbols, you 
will see that COUNT is undefined. 

The third message, 08 *** INVALID OR UNDEFINED OPERATION CODE, 

means that something is wrong with the COUNT definition statement. If you check 
the statement, you will see that the label, COUNT, starts in column two. The label 
must start in column one. 

After isolating the errors, you must go back to the source data set and correct them. 
Use $FSEDIT as explained in "Modifying an Existing Data Set" on page 3-5 to 
make the corrections. After you make the corrections, the source data set looks as 
follows: 



PROGl 


PROGRAM 


STPGM 


STPGM 


GETVALUE 


COUNT. 'ENTER NUMBER 


LOOP 


DO 


10, TIMES 




ADD 


SUM, COUNT 




ENDDO 






PRINTEXT 


'@RESULT=' 




PRINTNUM 


SUM 




PROGSTOP 




COUNT 


DATA 


F'G' 


SUM 


DATA 

ENDPROG 

END 


F'Q' 
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Rerunning the Compilation 



To rerun the compilation, return to the Session Manager Primary Option Menu and 
select option 2 (PROGRAM PREPARATION). 



$SMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



PRESS PF3 TO EXIT 



SELECT OPTION ==> 2 



20:02:07 
10/24/82 
ABCD 



1 - TEXT EDITING 

2 - PROGRAM PREPARATION 

3 - DATA MANAGEMENT 

4 - TERMINAL UTILITIES 

5 - GRAPHICS UTILITIES 

6 - EXEC PROGRAM/UTILITY 

7 - EXEC $JOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTIC AIDS 

10 - BACKGROUND JOB CONTROL UTILITIES 



The Program Preparation Option Menu appears on your screen. Select option 1 
(SEDXASM COMPILER). 






$SMM02 SESSION MANAGER PROGRAM PREPARATION OPTION MENU- 
ENTER/SELECT PARAMETERS: 



PRESS PF3 TO RETURN 



SELECT OPTION ==> 1 



1 - $EDXASM COMPILER 

2 - $EDXASM/$EDXLINK 

3 - $S1ASM ASSEMBLER 

4 - $COBOL COMPILER 

5 - $FORT FORTRAN COMPILER 

6 - $PLI COMPILER/$EDXLINK 

7 - $EDXLINK LINKAGE EDITOR 

8 - $XPSLINK LINKAGE EDITOR FOR SUPERVISORS 

9 - $UPDATE 

10 - $UPDATEH (HOST) 

11 - $PREFIND 

12 - $PASCAL COMPILER/$EDXLINK 

13 - $EDXASM/$XPSLINK FOR SUPERVISORS 

14 - $MSGUT1 MESSAGE SOURCE PROCESSING UTILITY 
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The SEDXASM Parameter Input Menu appears on your screen. Again, enter the 
name of your source input (in this example, ADD 10). Also enter the name of your 
object output (in this example, data set OBJECT on volume MYVOL). 



$SMm0201: session MANAGER $EDXASM PARAMETER INPUT MENU- 
ENTER/SELECT PARAMETERS: 

SOURCE INPUT (NAME, VOLUME) ==> ADD1O,EDX002 

OBJECT OUTPUT (NAME, VOLUME) ==> OBJECT, MYVOL 

OPTIONAL PARAMETERS ==> 
(SELECT FROM THE LIST BELOW) 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 



"^ 



DRCCC pn Tn DCTHDM 



AVAILABLE PARAMETERS: 
NOLIST 

LIST TERMINAL-NAME 
ERRORS TERMINAL-NAME 
CONTROL DATA SET, VOLUME 
OVERLAY # 



ABBREVIATION: 
NO 

LI TERMINAL-NAME 
ER TERMINAL-NAME 
CO DATA SET, VOLUME 
OV # 



DESCRIPTION: 
USED TO SUPPRESS LISTING 
USE LIST * FOR THIS TERMINAL 
USE ERRORS * FOR THIS TERMINAL 
$EDXASM LANGUAGE CONTROL DATASET 
# IS NUMBER OF AREAS FROM 1 TO 6 



DEFAULT PARAMETERS: 
LIST SSYSPRTR CONTROL $EDXL,ASMLIB OVERLAY 6 



J 



\^ 
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The following is an example of the output listing generated by the compiler. 
EDX ASSEMBLER STATISTICS 

SOURCE INPUT - ADD10,EDX002 
WORK DATA SET - $SM1ABCD,EDX002 
OBJECT MODULE - OBJECT, MYVOL 
DATE: 10/24/82 AT 20:06:18 
ASSEMBLY TIME: 4 SECONDS 
STATEMENTS PROCESSED - 12 



NO 


STATEMENTS FLAGGED 








LOC 


+0 


+2 


+4 


+6 +8 


SOURCE STATEMENT 


ADD10 ,EDX0O2 (5: 


0000 


0008 


D7D9 


D6D7 


D9C1 D440 


PROGl 


PROGRAM 


STPGM 


0034 


802C 


0074 


003 E 


0001 OEOE 


STPGM 


GETVALUE 


COUNT, 'ENTER NUMBER 


003 E 


C5D5 


E3C5 


D940 


D5E4 D4C2 








0048 


C5D9 


7A40 












004C 


809C 


0058 


0O0A 




LOOP 


DO 


10. TIMES 


0052 


0032 


0076 


0074 






ADD 


SUM, COUNT 


0058 


009D 


0000 


0001 






ENDDO 




005E 


8026 


0808 


D9C5 


E2E4 D3E3 




PRINTEXT 


'RESULT=' 


0068 


7E40 














006A 


0028 


0076 


0001 






PRINTNUM 


SUM 


0070 


0022 


FFFF 








PROGSTOP 




0074 


0000 








COUNT 


DATA 


F'O' 


0076 


0000 








SUM 


DATA 


F'O' 


0078 


0000 


0000 


0000 


0234 0000 




ENDPROG 




00FA 


0000 


0000 


0000 


0000 0000 








O10E 


0000 














0110 












END 





EXTERNAL/UNDEFINED SYMBOLS 

SVC WXTRN 
SUPEXIT WXTRN 
SETBUSY WXTRN 

COMPLETION CODE = -1 

The - 1 completion code tells you that the compile was successful. The next step is 
to link edit the object module into program data that can be executed. See the next 
chapter, Chapter 5, "Preparing an Object Module for Execution," for details. 
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^F**ik^ 



Chapter 5. Preparing an Object Module for Execution 

So far in this book, you have learned how to code and enter a source program into a 
data set. You have also learned how to compile the source program. 

The next step is to prepare your object modules for execution. In this chapter, we 
will show you how to use the Unkage editor $EDXLINK to prepare your object 
modules to run on an EDX system. SEDXLINK Unks together any separately 
assembled object modules that make up your program. SEDXLINK also produces a 
load module that is ready for execution. 

In this chapter, we will show you how to prepare a single object module for 
execution. We will also show you an example of Hnk editing more than one object 
module. 

You can load SEDXLINK in one of three ways. You can load SEDXLINK directly 
using the $L command. You can use the SJOBUTIL utihty to load SEDXLINK, or 
use SEDXLINK under control of the session manager. 

This chapter describes how to use SEDXLINK under control of the session manager. 
For information on using the $L command or the SJOBUTIL utility, refer to the 
Operator Commands and Utilities Reference. 



Link Editing a Single Object Module 

This section shows how to Hnk edit a single object module. 

SEDXLINK LINKAGE EDITOR is option 7 of the Session Manager Program 
Preparation Option menu. 

r 

$SMM02 SESSION MANAGER PROGRAM PREPARATION OPTION MENU 

ENTER/SELECT PARAMETERS: PRESS PF3 TO RETURN 

SELECT OPTION ==> 7 

1 - SEDXASM COMPILER 

2 - SEDXASM/SEDXLINK 

3 - SSIASM ASSEMBLER 

4 - $COBOL COMPILER 

5 - $FORT FORTRAN COMPILER 

6 - SPLI COMPILER/SEDXLINK 

7 - SEDXLINK LINKAGE EDITOR 

8 - SXPSLINK LINKAGE EDITOR FOR SUPERVISORS 

9 - SUPDATE 
IQ - SUPDATEH (HOST) 

11 - SPREFIND 

12 - SPASCAL COMPILER/SEDXLINK 

13 - $EDXASM/$XPSLINK FOR SUPERVISORS 

14 - SMSGUTl MESSAGE SOURCE PROCESSING UTILITY 



v.. 



J 
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When you select option 7 and press the enter key, the SEDXLINK Parameter Input 
Menu appears on your screen. 



$SMMO207: SESSION MANAGER $EDXLINK PARAMETER INPUT MENU- 
ENTER/SELECT PARAMETERS: 



rwLio rro lu rliumi 



EXECUTION PARM ==> * 

ENTER A CONTROL DATA SET NAME. VOLUME OR 
AN ASTERISK (*) FOR INTERACTIVE MODE. 

OUTPUT DEVICE (DEFAULTS TO $SYSPRTR) ==> 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 



^ 



You can run SEDXLINK in interactive mode. If you choose interactive mode, the 
system prompts you for information about the object module you want to link edit. 
To choose interactive mode, enter an asterisk (*) on the EXECUTION PARM hne. 

SEDXLINK then displays the following screen: 



LOADING $JOBUTIL nnP, hh:rini:ss, LP= xxxx, PART= yy 

REMARK 

SEDXLINK * 

*** JOB - SEDXLINK - STARTED AT 18:28:42 03/15/83 *** 

JOB SEDXLINK ($SMP0207) USERID=ABCD 

LOADING SEDXLINK nnP, hh:mm:ss, LP= xxxx, PART= yy 

SEDXLINK - EDX LINKAGE EDITOR 



SEDXLINK INTERACTIVE MODE 
DEFAULT VOLUME = EDX002 

STMT (?): 



O 



._y 



SEDXLINK prompts you for a control statement. Control statements are the 
instructions SEDXLINK uses to convert the object modules into load modules. 
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When using interactive mode, you enter the control statements one at a time. (As 
you will see later in this chapter, you can write the control statements to a link 
control data set for execution in noninteractive mode.) 

To link edit a single object module, use the INCLUDE and LINK statements. (You 
will learn about some of the other control statements later in this chapter.) 

The INCLUDE statement indicates which object module to use. (Remember that 
the object module is the output from SEDXASM, the compiler.) In this example, 
the object module is OBJECT. This is the only module name you enter next to the 
INCLUDE statement. 



LOADING $JOBUTIL nnP, hh:mm:ss, LP= xxxx, PART= yy 

REMARK 

$EDXLINK * 

*** JOB - SEDXLINK - STARTED AT 10:27:16 OO/QO/OO *** 

JOB $EDXLINK ($SMP02O7) USERID=ABCD 

LOADING $EDXLINK nnP. hh:niin:ss, LP= xxxx, PART= yy 

$EDXLINK - EDX LINKAGE EDITOR 



$EDXLINK INTERACTIVE MODE 
; DEFAULT VOLUME = EDXO02 

STMT (?): INCLUDE OBJECT, MYVOL 



Use the LINK statement to name the data set that is the output of SEDXLINK. 
When you enter the name of this data set, $EDXLINK allocates it. In the following 
example, the data set is named ADDPGM. It will reside on volume EDX002. The 
word REPLACE means to replace the program if it already exists on volume 
EDX002. The END statement signals $EDXLINK that the program contains no 
further source statements. 



LOADING $JOBUTIL nnP, hh:mm:ss, LP= xxxx, PART= yy 

REMARK 

$EDXLINK * 

*** JOB - $EDXLINK - STARTED AT 10:27:16 00/00/00 *** 

JOB SEDXLINK ($SMP0207) USERID=ABCD 

LOADING SEDXLINK nnP, hh:mni:ss, LP= xxxx, PART= yy 

SEDXLINK - EDX LINKAGE EDITOR 



SEDXLINK INTERACTIVE MODE 
DEFAULT VOLUME = EDX0O2 

STMT (?): INCLUDE OBJECT, EDXO02 

STMT (?): LINK ADDPGM, EDX002 REPLACE END 



Chapter 5. Preparing an Object Module for Execution 5-3 



Preparing an Object Module for Execution 



The system produces a data set (ADDPGM) that can now be executed on the 
system. In this example, we Unk edited only one object module (OBJECT). The 
next section shows how to Unk edit more than one object module. 

If the system indicates (by returning a — 1 completion code) that the link edit was 
successful, return to the Primary Option Menu to execute your program. For 
information on how to execute your program see Chapter 6, "Executing a 
Program." 



o 



Link Editing IVIore Than One Object fVlodule 



This section shows how to specify that a load module consists of more than one 
object module. If you divide a large program into modules, those modules can be 
compiled separately. If you need to make a change to one of the modules, you need 
to recompile only that module. When you are ready to run the program, you can 
Unk edit the individual modules. 

You might also have a function that is common to many of your programs. By 
making this function a separate module, you could include it wherever needed in 
your programs. 



This section shows how to use both interactive and noninteractive mode to Unk edit 
the modules. All examples show $EDXLINK being used under control of the 
session manager. 

As you learned earUer in this chapter, $EDXLINK LINKAGE EDITOR is option 7 
of the Session Manager Program Preparation Option menu. 



\^ 



r~ 



$SMM02 SESSION MANAGER PROGRAM PREPARATION OPTION MENU- 
ENTER/SELECT PARAMETERS: 

SELECT OPTION ==> 7 



PRESS PF3 TO RETURN 



1 - SEDXASM COMPILER 

2 - $EDXASM/$EDXLINK 

3 - $S1ASM ASSEMBLER 

4 - SCOBOL COMPILER 

5 - $FORT FORTRAN COMPILER 

6 - SPLI COMPILER/SEDXLINK 

7 - $EDXLINK LINKAGE EDITOR 

8 - $XPSLINK LINKAGE EDITOR FOR SUPERVISORS 

9 - $UPDATE 

10 - SUPDATEH (HOST) 

11 - $PREFIND 

12 - $PASCAL COMPILER/SEDXLINK 

13 - $EDXASM/$XPSLINK FOR SUPERVISORS 

14 - SMSGUTl MESSAGE SOURCE PROCESSING UTILITY 



\J 
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When you select option 7, the SEDXLINK Parameter Input Menu appears on your 
screen. 



$SMM0207: SESSION MANAGER $EDXLINK PARAMETER INPUT MENU 

ENTER/SELECT PARAMETERS: PRESS PF3 TO RETURN 



EXECUTION PARM ==> * 

ENTER A CONTROL DATA SET NAME, VOLUME OR 
AN ASTERISK {*) FOR INTERACTIVE MODE. 

OUTPUT DEVICE (DEFAULTS TO $SYSPRTR) ==> 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 



Including Individual Object Modules 

With the INCLUDE statement, you indicate which object modules to use. If the 
modules reside on the same volume, you can hst them on one INCLUDE statement. 
In the example shown below, the first INCLUDE statement includes four object 
modules from volume EDX003. The second INCLUDE statement includes two 
object modules from volume MYVOL. 



LOADING $JOBUTIL nnP, hh:mm:ss, LP= xxxx, PART= yy 

REMARK 

$EDXLINK * 

*** JOB - $EDXLINK - STARTED AT 07:27:16 00/00/00 *** 

JOB $EDXLINK ($SMPO207) USERID=ABCD 

LOADING $EDXLINK nnP, hh:mm:ss, LP= xxxx, PART= yy 

$EDXLINK - EDX LINKAGE EDITOR 



$EDXLINK INTERACTIVE MODE 
DEFAULT VOLUME = EDXO02 

STMT (?): INCLUDE OBJ12,OBJ13,OBJ14,OBJ15,EDXO03 

STMT (?): INCLUDE SQRT,STDEV, MYVOL 



After you enter the first INCLUDE statement, $EDXLINK prompts you for 
another statement. Enter the second INCLUDE statement. 
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The LINK statement tells the linkage editor what to call the load module and where 
to put it. In this example, the output object data set will be named PGM 1 . It will 
reside on volume EDX003. The word REPLACE means to replace the program if 
it already exists on volume EDX003. The END statement signals $EDXLINK that 
the program contains no further source statements. 



c 



STMT (?): INCLUDE 0BJ12,0BJ13,0BJ14,0BJ15,EDX003 
STMT (?): INCLUDE SQRT,STDEV,MYVOL 
STMT {?): LINK PGM1,EDX003 REPLACE END 



$EDXLINK EXECUTION STARTED 
PGMl ,EDX0Q3 STORED 
PROGRAM DATA SET SIZE = 
COMPLETION CODE = -1 



7 RECORDS 



V^. 



$EDXLINK ENDED AT 09:33:35 
SJOBUTIL ENDED AT 09:33:55 
PRESS ENTER KEY TO RETURN 



Once you enter these statements, SEDXLINK produces a load module (PGMl) that 
is ready for execution. PGMl consists of six object modules: OBJ 12, OBJ 1 3, 
OBJ 14, OBJ 15, SQRT, and STDEV. 






c 
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Including Overlay Segments 

Your program may include overlay segments. (Overlay segments are described in 
detail in "Reusing Storage using Overlays" on page 9-9.) You use the OVERLAY 
statement to identify these segments to $EDXLINK. 

For example, suppose you had a program made up of a resident segment and two 
overlays. Assume the name of the resident segment is TESTROOT and the overlays 
are named TESTSUB 1 and TESTSUB2. Your control statements would look like 
this: 






$EDXLINK INTERACTIVE MODE 
DEFAULT VOLUME = EDX002 

STMT (?): INCLUDE TESTROOT, EDX003 

STMT {?): OVERLAY 

STMT {?): INCLUDE TESTSUB1,EDX003 

STMT (?): OVERLAY 

STMT (?): INCLUDE TESTSUB2,EDX003 

STMT (?): LINK TEST.EDXOOS REPLACE END 

$EDXLINK EXECUTION STARTED 
TEST .EDXO03 STORED 
PROGRAM DATA SET SIZE = 26 
COMPLETION CODE = -1 

SEDXLINK ENDED AT 04:05:35 



The first INCLUDE statement identifies the resident (or root) portion of the 
program. The INCLUDE statement following the first OVERLAY statement 
identifies the first overlay segment. The INCLUDE statement following the second 
OVERLAY statement identifies the second overlay segment. 

The LINK statement identifies the object output data set. 
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Using, the Autocall Feature 

You can use the AUTOCALL control statement to load the autocall feature. You 
can include up to three autocall data set names on the AUTOCALL statement. 
Autocall data sets contain a hst of object module names and volumes, along with 
their entry points. Use the autocall option to include modules not explicitly included 
with the INCLUDE statement. 



You need to use autocall data sets if, for example, you are link editing a program 
that uses $IMAGE subroutines. Some instructions, such as GETEDIT and 
PUTEDIT, also require that you link edit with the autocall option. 

The following is an example of an autocall data set. 

PGM1,EDXO03 ENTER 

PGM2,EDX40 START 

PGM3,MYV0L CALC 
**END 



PGMl, PGM2, and PGM3 are object modules on EDX003, EDX40, and MYVOL. 
ENTER, START, and CALC are the entry points for the modules. The module 
names must begin in column one and end with an **END statement. 

Enter the AUTOCALL statement just before the LINK statement. This example 
specifies two autocall data sets: the system-supplied autocall data set (SAUTO on 
volume ASMLIB) and data set MY AUTO on volume MYVOL. 

If you specify more than one AUTOCALL statement, the hnkage editor uses the last 
one. 

Suppose you wanted to add an AUTOCALL statement to the previous example. 
You would enter it hke this: 



W 



$EDXLINK INTERACTIVE MODE 
DEFAULT VOLUME = EDX0O2 

STMT (?): INCLUDE TESTR00T,EDX003 

STMT (?): OVERLAY 

STMT {?): INCLUDE TESTSUB1,EDX003 

STMT {?): OVERLAY 

STMT (?): INCLUDE TESTSUB2,EDX003 

STMT (?): AUTOCALL $AUT0, ASMLIB MYAUTO, MYVOL 

STMT {?): LINK TEST,EDX0O3 REPLACE END 



y 
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The system would respond as follows: 



$EOXLINK EXECUTION STARTED 
TEST ,EDXO03 STORED 
PROGRAM DATA SET SIZE = 26 
COMPLETION CODE = -1 



$EDXLINK ENDED AT 04:05:35 



The Hnkage editor also prints, on the system printer, the names of the object 
modules it included. For example: 

INCLUDE $IMOPEN ,ASMLIB FROM $AUTO ,ASMLIB VIA AUTOCALL 

INCLUDE $IMGEN ,ASMLIB FROM $AUT0 ,ASMLIB VIA AUTOCALL 

INCLUDE $6PLIST ,ASMLIB FROM $AUT0 ,ASMLIB VIA AUTOCALL 

INCLUDE $GEER ,ASMLIB FROM $AUT0 ,ASMLIB VIA AUTOCALL 

INCLUDE $GEAC ,ASMLIB FROM $AUTO ,ASMLIB VIA AUTOCALL 

INCLUDE $IMDTYPE,ASMLIB FROM $AUTO ,ASMLIB VIA AUTOCALL 

INCLUDE $$RETURN,ASMLIB FROM $AUTO ,ASMLIB VIA AUTOCALL 

INCLUDE $UNPACK ,ASMLIB FROM $AUTO ,ASMLIB VIA AUTOCALL 

Using Noninteractive Mode 

Using noninteractive mode means that you do not have to enter control statements 
each time you link edit a program. 

When you use noninteractive mode, you must enter the name of a primary control 
data set on the SEDXLINK Parameter Input Menu. The primary control data set 
contains the control statements to be used by SEDXLINK. 

You can create the primary control data set using SFSEDIT. Then enter control 
statements into the data set. 

The following is an example of a primary control data set. Control statements must 
begin in column 1 . This data set includes comment statements. A comment 
statement begins with an asterisk (*). 

* PLOT PROGRAM INCLUDES 
* 

INCLUDE PLOTXY,MYVOL 
INCLUDE PLOTXX,MYVOL 
INCLUDE PLOTYY,MYVOL 

INCLUDE PLOTYX,MYVOL 

* 

* PERFORM AUTOCALL PROCESSING USING: 

* 

AUTOCALL MYAUTO,MYVOL $AUTO,ASMLIB 
* 

* PERFORM THE LINK 
* 

LINK PLOT,MYVOL REPLACE END 
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After entering these statements into the data set, specify the name of this data set 
next to "EXECUTION FARM" on the SEDXLINK Parameter Input Menu. In this 
example, the data set is LINKl on volume EDX003. 



o 



$SMM02O7: SESSION MANAGER SEDXLINK PARAMETER INPUT MENU- 
ENTER/SELECT PARAMETERS: 



PRESS PF3 TO RETURN 



EXECUTION PARM ==> LINKl, EDX0G3 

ENTER A CONTROL DATA SET NAME, VOLUME OR 
AN ASTERISK (*) FOR INTERACTIVE MODE. 

OUTPUT DEVICE (DEFAULTS TO SSYSPRTR) === 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 



The primary control data set can also refer to a secondary control data set. The 
secondary control data set contains additional control statements. These control 
statements can be common control statements that are used frequently for many 
different Hnk edits. You use the COPY control statement to refer to these secondary 
data sets. For example: 

INCLUDE ASMOBJ,EDX0O3 

COPY CTRL,EDX40 

LINK PGM3,EDX40 REPLACE END 

The linkage editor includes object module ASMOBJ on volume EDX003, copies 
additional control statements from data set CTRL on volume EDX40, gives the load 
module the name PGM 3, and puts it on volume EDX40. 

For more information on specifying primary and secondary control statement data 
sets, refer to the Operator Commands and Utilities Reference. 



kJ 



Prefinding Data Sets and Overlays 



You can locate data sets and overlay programs before you load a program by usin^ 
the $PREFIND utiUty. You can improve program performance by using 
SPREFIND. 



You should use $PREFIND if: 

• The program uses a large number of data sets. 

• The program loads several overlay programs. 

• You load the program frequently. 

For information on how to use the $PREFIND utility, refer to the Operator 
Commands and Utilities Reference. 
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Chapter 6. Executing a Program 



After you have compiled and link edited a program, you are ready to run (or 
execute) it. 

This chapter shows how to execute a program. You can execute a program in any 
of the following ways: 

• You can load the program with the $L operator command. 

• You can use the SJOBUTIL utihty. 

• You can use the session manager. 

• You can submit the program from another program. 

• You can use the $SUBMIT utihty. 

This chapter describes how to use the session manager to execute a program and 
how to submit a program from another program. For information on how to use 
the $L operator command or the SJOBUTIL utihty or the $SUBMIT utihty, refer to 
the Operator Commands and Utilities Reference. 



Executing a Program with the Session l\/ianager 

To execute your program, select option 6 (EXEC PROGRAM/UTILITY) on the 
Primary Option Menu. 



SSMMPRIM: SESSION MANAGER PRIMARY OPTION MENU 
ENTER/SELECT PARAMETERS: 



SELECT OPTION ==> 6 



1 - TEXT EDITING 

2 - PROGRAM PREPARATION 

3 - DATA MANAGEMENT 

4 - TERMINAL UTILITIES 

5 - GRAPHICS UTILITIES 

6 - EXEC PROGRAM/UTILITY 

7 - EXEC SJOBUTIL PROC 

8 - COMMUNICATION UTILITIES 

9 - DIAGNOSTIC AIDS 

10 - BACKGROUND JOB CONTROL UTILITIES 



PRESS PF3 TO EXIT 
11:42:07 



10/24/82 



ABCD 



J 
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The Execute Program/Utility menu appears. Enter the program name (ADDPGM) 
and volume (EDX002) next to PROGRAM/UTILITY (NAME,VOLUME). Then 
type an asterisk in the DATA SET 1, DATA SET 2, and DATA SET 3 fields and 
press the enter key. 



$SMMG& SESSION MANAGER EXECUTE PROGRAM/UTILITY — 
ENTER/SELECT PARAMETERS: 

PROGRAM/UTILITY (NAME, VOLUME) ==> ADDPGM, EDXO02 
DYNAMIC STORAGE (OPTIONAL) ==> 

PARAMETERS ===> 

DATA SET 1 (NAME, VOLUME / * = DSl NOT USED) ===> 
DATA SET 2 (NAME, VOLUME / * = DS2 NOT USED) ===> 
DATA SET 3 (NAME, VOLUME / * = DS3 NOT USED) ===> 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 



PRESS PF3 TO RETURN 



V. 



NOTE: IF A DATA SET (DSl, DS2 OR DS3) IS NOT USED, 

AN ASTERISK (*) MUST BE ENTERED IN THE DATA SET FIELD. 



.J 



Putting asterisks in the DATA SET fields means either of two things. Either the 
program does not use any data sets or the program specifies the data sets with the 
DS operand. For example, the PROGRAM for program ADDPGM might look Uke 
this: 

BEGIN PROGRAM ST 

or this: 

BEGIN PROGRAM ST,DS=( (MASTER, EDX003) , (UPDATES, MYVOL) ,(NEWMAST,EDX40)) 

If you want the program to execute in the background, enter B next to 
FOREGROUND OR BACKGROUND (F/B). Otherwise, the system executes the 
program in the foreground. 

After you press the enter key, the following screen appears on the terminal: 



LOADING SJOBUTIL nnP, hh:nim:ss, LP= xxxx, PART= y 

REMARK 

EXECUTE PROGRAM/UTILITY: ADDPGM 

*** JOB - ADDPGM - STARTED AT 11:48:22 00/00/00 *** 

JOB ADDPGM ($SMP06) USERID=ABCD 

LOADING ADDPGM nnP. hh:mm:ss, LP= xxxx, PART= y 

ENTER NUMBER: 



J 
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Specifying Data Sets 

You can specify data sets in any of these ways: 

1 In the DS = operand of a PROGRAM instruction 

2 In the DS = operand of a LOAD instruction 
J With the $L operator command 

4 During execution of some system utility programs 

5 On the Execute Program/Utility menu 

6 With the DS command of the $JOBUTIL utihty. 
You identify a data set by specifying: 

1 The data set name (dsname) 

2 An optional volume label (volume) which specifies the volume on which the 
data set resides. 

The format for a data set specification is: 
dsname, volume 

Volume is optional. If you omit volume, the system assumes that the data set resides 
on the volume from which you performed an IPL. Definitions of dsname and 
volume are: 

dsname An alphanumeric character string of eight characters. When you specify 
fewer than eight characters, the system adds blanks to the right to 
complete the string. 

volume An alphanumeric character string of six characters. To locate the 

volume, the appropriate TAPE or DISK statement must be in the system 
I/O definition. You must initiaUze the disk or diskette with the 
SINITDSK utihty and tapes with the $TAPEUT1 utihty. When you 
specify fewer than six characters, the system adds blanks to the right to 
complete the string. 



^ttf^' 
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To specify up to three data sets on the Execute Program/Utility menu, enter the data 
set name and volume as in the following example: 



$SMM06 SESSION MANAGER EXECUTE PROGRAM/UTILITY- 

r-niTrr* /rri r-r»T nAnflmrTrnc- 



O 



PR 



'"i )o ri J I <j i\L.iui\iii 



PROGRAM/UTILITY (NAME, VOLUME) ==> ADDPGM,EDX002 
DYNAMIC STORAGE (OPTIONAL) ==> 

PARAMETERS ===> 

DATA SET 1 (NAME, VOLUME / * = DSl NOT USED) ===> MASTER, EDX003 
DATA SET 2 (NAME, VOLUME / * = DS2 NOT USED) ===> UPDATES, MYVOL 
DATA SET 3 (NAME, VOLUME / * = DS3 NOT USED) ===> NEWMAST,EDX40 

FOREGROUND OR BACKGROUND (F/B) ==> 
(DEFAULT IS FOREGROUND) 

NOTE: IF A DATA SET (DSl, DS2 OR DS3) IS NOT USED, 

AN ASTERISK (*) MUST BE ENTERED IN THE DATA SET 
FIELD. 



The PROGRAM statement for program ADDPGM might look Hke this: 
BEGIN PROGRAM ST, DS=(??, ??,??) 

If a program requires fewer than three data sets, enter an asterisk (*) next to the 
data set(s) not used. 
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Submitting a Program from Another Program 



A program can submit one or more programs to the EDX job processor. The job 
queue processor executes the programs independently of the program that submitted 
them. 



The following example shows how one program can submit programs CALC on 
volume EDX003 and UPDATE on volume MYVOL. The explanation for each 
numbered step appears on the next page. 

BEGIN PROGRAM START 
START EQU * 



LOAD $SUBMITP,SUBPARM1,L0GMSG=N0,EVENT=SUBEND 

WAIT SUBEND 

IF (SUBEND, NE,-1) 

PRINTEXT 'ERROR LOADING CALC',SKIP=1 
ENDIF 



□ 






LOAD $SUBMITP,SUBPARM2,L0GMSG=N0,EVENT=SUBEND 

WAIT SUBEND 

IF (SUBEND, NE,-1) 

PRINTEXT "ERROR LOADING UPDATE" , SKI P=l 
ENDIF 







PROGSTOP 




SUBEND 


ECB 




SUBPARMl 


EQU 


* 






DATA 


C"SJ' 






DATA 


X"0O02" 






DATA 


CLS'JOBOl" 






DATA 


CL6'EDX40' 






DATA 


A(JOBNO) 


SUBPARM2 


EQU 


* 




DATA 


C'SJ' 




DATA 


X"O002" 




DATA 


CL8'JOB02' 




DATA 


CL6'EDX40' 




DATA 


A(JOBNO) 


EOjobno 


DATA 
ENDPROG 


F'O' 






END 
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Q Submit a job to the job queue. Point to a parameter list called SUBPARMl, 
and identify the event to be posted when the job has been submitted 
(EVENT = SUBEND). 

01 Wait for the job to be submitted to the job queue. 

B Test for successful completion (-1) of the submit. 

Q Submit a job to the job queue. Point to a parameter hst called SUBPARM2, 
and identify the event to be posted when the job has been submitted 
(EVENT = SUBEND). 

Q Specify that the job is to be submitted (SJ). 

Q Specify the priority of the job (0002). 

Q Identify the name of the data set that contains the job stream processor 
commands (JOBOl). 

B Specify the volume that contains JOBOl (EDX40). 

Q Specify the address of the field in which the system will put the job number 
(JOBNO). 

IB Reserve storage for the system to put the job number. 

The data set called JOBOl contains job stream processor commands. It might look 
like the following: 

JOB JOBOl 

PROGRAM CALC,EDX0O3 

EXEC 

EOJ 

The PROGRAM command refers to a program called CALC on volume EDX003. 

The data set called JOB02 contains job stream processor commands. It might look 
hke the following: 

JOB J0B02 

PROGRAM UPDATE, MYVOL 

EXEC 

EOJ 

The PROGRAM command refers to a program called UPDATE on volume 
MYVOL. 



o 
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Chapter 7. Finding and Fixing Errors 



Up to this point, you have written, compiled, and hnk edited your program. 
However, the program may not run as you expect it to. Steps may be out of 
sequence or the program may come up with the wrong answers. In other words, you 
have problems with your program's logic. 

The program also may not run to a successful conclusion. An exception condition 
may occur that interrupts the execution of a program. 

The SDEBUG utility assists you in determining logic errors. The task error exit 
routine is one of the tools you can use to diagnose exception conditions. 



Determining Logic Errors in a Program 



This section tells you how to locate and fix logic errors in your program by using the 
SDEBUG utility. $DEBUG can work from terminals; you do not have to use the 
console. SDEBUG has commands that allow you to: 

• Stop execution at one or more specific places in a program. The places where 
you choose to stop a program are called breakpoints. 

• Set up a trace routine. A trace routine allows you to step through program 
instructions one at a time. You must specify one or more parts of the program 
you wish to trace (called a trace range). Each time the program executes an 
instruction within any of the specified trace ranges, the terminal displays a 
message identifying the task name and the instruction address just executed. 
You can stop program execution after each instruction executes within a trace 
range. 

• List additional registers and storage location contents while the program is 
stopped at a breakpoint or at an instruction within a trace range. 

• Change the contents of storage locations, registers, data, or instructions. 

• Restart program execution. You can restart execution at the breakpoint or trace 
range address where it is currently stopped or you may specify another 
instruction address. 
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Creating and Running the Program 

This section shows an EDL program that has a logic error in it. It shows briefly 
how to enter, compile, link edit, and run (execute) the program. 

Perform the follov»'ing steps using the session manager. Give the program the name 
ADDIO. If you have any problems, see Chapter 3, "Entering a Source Program." 



1 Enter the following program on your terminal exactly as shown. 



ADDIO 


PROGRAM 


STPGM 


STPGM 


GETVALUE 


COUNT, 'EN 


LOOP 


DO 


10, TIMES 




ADD 


COUNT, SUM 




ENDDO 






PRINTEXT 


'RESULT=' 




PRINTNUM 


SUM 




PROGSTOP 




COUNT 


DATA 


F'O' 


SUM 


DATA 

ENDPROG 

END 


F'O' 



This program is supposed to take a number entered on a terminal and add it 
to itself 10 times. For example, if you enter the number 10, you should get 
the response: RESULT = 100. However, because of a program logic error, 
you will not get the expected answer when you run the program. 

2 Now compile the program. If you have any problems, see \^^ 

Chapter 4, "Compihng a Program." Save the compiler listing. You will need 
it when you run $DEBUG. 

J Next, hnk edit your program. If you have any problems, see 
Chapter 5, "Preparing an Object Module for Execution." 

4 Run the program. If you have any problems, see Chapter 6, "Executing a 
Program." 

When the prompt ENTER NUMBER appears, enter the number 10. 



ENTER NUMBER: 10 

RESULT= Q 
._._ , .. J 



Because this program has a logic error, the answer returned is 0. The expected result 
was 100. 



7-2 SC34-0943 



■^ In 



Finding and Fixing Errors 



Debugging and Fixing ttie Program 

This section describes how to use SDEBUG to find and correct a logic error. 

Loading $DEBUG 

To start debugging the program, do the following: 

1 End the session manager. You cannot run SDEBUG while the session 
manager is active. One way to load SDEBUG is with the SL operator 
command. 

2 Enter the following: 
> $L SDEBUG 



The following message appears, telling you that SDEBUG is being loaded. 
LOADING SDEBUG nnP, hh:inm:ss, LP= xxxx, PART= y 



J Then SDEBUG asks for the name of the program to be debugged. Respond 
as follows: 



PROGRAM (NAME, VOLUME): ADD10,EDX0G2 



4 The utility then prompts for a partition number and a terminal name: 



PARTITION (DEFAULT IS CURRENT PARTITION): 
! TERMINAL NAME (DEFAULT IS CURRENT TERMINAL) : 



If you press enter after each of the prompts, the system uses the current 
partition and terminal. 

SDEBUG then displays the following information: 



LOADING ADDIO nnP, hh:mm:ss, LP= xxxx, PART= y 

REQUEST "HELP" TO GET LIST OF DEBUG COMMANDS 
ADD10 STOPPED AT 0034 
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These messages tell you: 

• The load point (LP = BDOO) of the program 

• The partition where $DEBUG loaded the program (PART = 1) 

• That $DEBUG set a breakpoint and stopped the program at address 0034, 
which is the first executable instruction. 



o 



Note that you can also enter HELP to see a hst of the available $DEBUG 
commands. 



$DEBUG Commands 



Both SDEBUG and the program have been loaded into partition 1. The program 
has stopped and $DEBUG is waiting for a command. To see a list of the $DEBUG 
commands: 

1 Press the attention key. 

2 Enter HELP. 

The list of $DEBUG commands appears on the screen. 



f 

> HELP 




A 


THE FOLLOWING COMMANDS ARE AVAILABLE: 




HELP 


- LIST DEBUG COMMANDS 




WHERE 


- DISPLAY TASK STATUS 




LIST 


- DISPLAY STORAGE OR REGISTERS 




PATCH 


- MODIFY STORAGE OR REGISTERS 




QUALIFY 


- MODIFY BASE ADDR 




AT 


- ESTABLISH BREAKPOINTS 




OFF 


- REMOVE BREAKPOINTS 




GO 


- START TASK PROCESSING 




POST 


- POST EVENT OR PROCESS INTERRUPT 




PRINT 


- DIRECT LISTING TO PRINTER 




BP 


- LIST BREAK POINTS 




GOTO 


- CHANGE EXECUTION SEQUENCE 




CLOSE 


- CLOSE SPOOL JOB CREATED BY $DEBUG 




END 


- TERMINATE DEBUG FACILITY 




V 




J 
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Use the $DEBUG commands to: 

List SDEBUG commands (HELP). 

Display the current status of each task (WHERE). 

Display storage or register contents (LIST). 

Change storage or register contents (PATCH). 

Change the base address (QUALIFY). 

Set breakpoints and trace ranges (AT). 

Remove breakpoints and trace ranges (OFF). 

Restart a stopped task (GO). 

Start a task waiting for an event or process interrupt (POST). 

Direct output to another terminal (PRINT). 

List breakpoints and trace ranges (BP). 

Restart a stopped task at a different instruction (GOTO). 

Close a spool job that was created by SDEBUG (CLOSE). 

End SDEBUG (END). 



JTX 



You can enter any of the commands by pressing the attention key and entering the 
command name. SDEBUG then prompts for the command parameters. For 
example, if you want to set a breakpoint, enter the AT command. SDEBUG then 
prompts for the parameters as shown below. 



AT 



ADDR 



OPTION (*/ADDR/TASK/ALL) 

BREAKPOINT ADDRESS: 4C 

LIST/NOLIST: LIST 

OPTION(*/ADDR/RO. . .R7/#l/#2/IAR/TC0DE/UNMAP) 

LENGTH: 1 

MODE(X/F/D/A/C): X 

STOP/NOSTOP: STOP 

1 BREAKPOINT(S) SET 



#1 



This command sets a breakpoint at address 4C. It requests that SDEBUG print the 
contents of register 1 (one word) in hexadecimal. STOP tells SDEBUG to stop at 
address 4C. 

For detailed syntax descriptions, refer to each individual command in the Operator 
Commands and Utilities Reference. 

You can also enter a command and its parameters without going through the 
prompts. For example: 



> AT ADDR 4C L #1 1 X S 






gives you the same results. 
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Finding the Errors 



Now that you have loaded SDEBUG, specified your program name, and reviewed 
the SDEBUG commands, you are ready to start finding the logic errors in your 
program. You should have a hsting of the program before you start. Then follow 
these steps: 

1 Use the AT command to set a breakpoint to stop the program after the 
GETVALUE executes (address 004C). Respond to the prompts as follows: 



> AT 

OPTION{*/ADDR/TASK/ALL): ADDR 
BREAKPOINT ADDR: 004C 
LIST/NOLIST: NOLIST 
STOP/NOSTOP: STOP 

1 BREAKPOINT (S) SET 



The breakpoint to stop after the GETVALUE instruction executes is now set. 
2 Enter a GO command and, when prompted, enter the number 10. 



> GO 

1 BREAKPOINT(S} ACTIVATED 
ENTER NUMBER: 10 
ADDIG STOPPED AT 004C 



Program execution has stopped at the instruction labeled LOOP. The 
GETVALUE instruction has executed. 

To check to see if the program read the data correctly, use the LIST command 
to display data field COUNT at address 0074. 



J Enter a LIST command and respond as follows: 



V_ 



> LIST 

OPTION {*/ADDR/RO. . .R7/#l/#2/IAR/TC0DE/UNMAP) : ADDR 
ADDRESS: 0074 
LENGTH: 1 

MODE(X/F/D/A/C): D 
0074 D' 0010' 



The LIST command shows that 0074 contains 10, the correct input. This 
indicates proper logic to this point. 

The next set of instructions is the DO loop. Set another breakpoint to stop 
the program after execution of the DO loop at address 005E. 
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4 Enter an AT command and respond as follows: 



> AT 

OPTION (*/ADDR/TASK/ALL): ADDR 
BREAKPOINT ADDR: 0O5E 
LIST/NOLIST: MOLIST 
STOP/NOSTOP: STOP 

1 BREAKPOINT(S) SET 



The breakpoint to stop after the DO loop instructions executes is now set. 
J Enter a GO command and the following occurs: 

> GO 

1 BREAKPOINT(S) ACTIVATED 
ADD10 STOPPED AT 005E 






Fixing the Problem 






At this point, the data field SUM at address 0076 should contain the number 
100. 

To check to see if the data field SUM contains the proper number, use the 
LIST command to display data field SUM at address 0076. 



6 Enter a LIST command and respond as follows: 



> LIST 

OPTION{*/ADDR/RO. . .R7/#l/#2/IAR/TC00E/UNMAP) : ADDR 
ADDRESS: 0076 
LENGTH: 1 

M0DE(X/F/D/A/C): D 
0Q76 D' 0OOG' 



The LIST command shows that this field contains zero. This means that the 
DO loop or the ADD instruction in the DO loop is incorrect. If you examine 
these instructions, you will see that the DO loop is correct. However, The 
ADD instruction has a logic error. In order to receive the proper answer, the 
COUNT field should be added to the SUM field. The operands are 
backwards. The DO loop executes the ADD instruction 10 times but is 
adding SUM to COUNT, causing the SUM field to remain 0. 



To verify that this is the problem without having to recompile and hnk edit the 
program, you can use the PATCH command of $DEBUG for a temporary fix. This 
fix is good only for one execution of the program. PATCH only fixes the copy of 
the program loaded by SDEBUG. It does not fix the program on your volume. 
Once you have verified that the fix is correct, you can then change the program on 
your volume. 
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To verify that the problem is the ADD instruction, do the following: 

1 Find address 0052 on your compiler listing. This line contains the ADD 
instruction. The entire Hne looks like this: 



0052 0032 00/4 0076 



ADD 



tuuiNi ,5un 



The address of the instruction is 0052. The operation code (0032) does not 
change. The next two words, 0074 and 0076, are the addresses of data fields 
COUNT and SUM. 

To fix the logic error, change the instruction to look as follows: 
0052 0032 0076 0074 

2 Enter a PATCH command and respond to the prompts as follows: 



> PATCH 

OPTION ( */ADDR/R0...R7/#l/#2/IAR/TC0DE/UNMAP): ADDR 
ADDRESS: 0054 
LENGTH: 2 

MODE(X/F/D/A/C): A 
NOW IS 

0054 A' 0074 0076' 
DATA: 0076 0074 
NEW DATA 

0054 A' 0076 0074' 
YES/NO/CONTINUE: YES 



.iT^ 



The program is now patched. When it executes, it will add COUNT to SUM 
to arrive at the expected result. You can test the change by reexecuting the 
program. 

To reexecute the program, you have to know two things: the address where 
the program is currently stopped (005E) and the address of the first executable 
instruction (0034). Then you can use the GOTO command to restart the 
program at the first executable instruction. 

D Enter a GOTO command as shown: 



V 



j^ 



> GOTO O05E 0034 

1 BREAKPOINT(S) ACTIVATED 
ADDIO STOPPED AT 0034 



4 The program is now at the beginning. To test it, set all the breakpoints off so 
that the program will run to completion. 

Enter the following: 
> OFF ALL 



J 
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J Now enter a GO command and respond to the prompts as follows: 



> GO 

ENTER NUMBER: 10 
RESULTS= 100 
ADDIO ENDED AT 00:27:56 



This time you received the expected result of 100. You have verified that the 
logic error was the ADD instruction. 



Now that you have found and fixed the logic error in your program, use the END 
command to terminate $DEBUG. Enter the following: 



> END 



When SDEBUG ends, your program remains in storage with all of its tasks active 
and operating if it has not already ended. In our example, however, the program 
has ended. 



m^ ,1/ 



To make the fix permanent, change your source program (see Chapter 3, "Entering 
a Source Program"), recompile it (see Chapter 4, "Compiling a Program"), and 
hnk edit your object code module (see Chapter 5, "Preparing an Object Module for 
Execution"). 



Displaying Unmapped Storage 



If you write a program that uses unmapped storage, you may want to display 
portions of unmapped storage. Displaying unmapped storage may be necessary to 
determine whether or not a program is processing correctly. 

This section shows how to display a portion of unmapped storage. The program 
example used in this section is shown in "Sample Program" on page 7-12. 

The program moves mortality rates to the unmapped storage areas. To find out if 
the rates are being moved properly, you can display an unmapped storage area as 
follows: 



1 Load SDEBUG and specify your program name: 



> $L $DEBUG 



The following message appears, telling you that the system is loading 
SDEBUG. 



o 



LOADING SDEBUG 



nnP, hh:mm:ss, LP= xxxx, PART= y 
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-2 When SDEBUG asks for the name of the program to be debugged, respond as 
follows: 



PROGRAM NAME: INSURE, EDX40 



J The utihty then prompts for a partition number and a terminal name: 



PARTITION (DEFAULT IS CURRENT PARTITION): 
TERMINAL NAME (DEFAULT IS CURRENT TERMINAL) 



If you press enter after each of the prompts, the system uses the current 
partition and terminal. 

4 Use the AT command to set a breakpoint to stop the program after the 
ENDIF statement that follows the two MOVE instructions that move the 
rates to the unmapped storage area (address 152). Respond to the prompts as 
follows: 



> AT 

OPTION (*/ADDR/TASK/ALL): ADDR 
BREAKPOINT ADDR: 0152 
LIST/NOLIST: NOLIST 
STOP/NOSTOP: STOP 

1 BREAKPOINT (S) SET 



3 Enter a GO command. 



> GO 

1 BREAKPOINT(S) ACTIVATED 
INSURE STOPPED AT 0152 



Program execution has stopped at the ENDIF statement. One of the MOVE 
instructions has executed. 

6 To see if the program moved data correctly, first find the number of the 
unmapped storage area. CNTRYC (address 02AE) contains the number of 
the unmapped storage area obtained with the SWAP instruction. 



V. 



> LIST 

OPTION(*/ADDR/RO. . .R7/#l/#2/IAR/TC0DE/UNMAP) : ADDR 
ADDRESS: 02AE 
LENGTH: 1 

MODE(X/F/D/A/C): X 
02AE X' 0003' 
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The SWAP instruction obtained unmapped storage area number 3. 

Then display storage in unmapped storage area number 3, using the LIST 
command as follows: 



> LIST 

OPTION (*/ADDR/R0. . .R7/#l/#2/IAR/TC0DE/UNMAP) 
STORBLK ADDRESS (0 TO CANCEL LIST) : 04B4 
SWAP#: 3 
DISPLACEMENT: 
LENGTH: 20 
MODE(X/F/D/A/C): C 
0000 C 00010002000300030004' 



UNMAP 



This LIST command shows the contents of the unmapped storage area. It 
contains five sets of four-digit numbers that could be mortaUty rates. Check 
the input data to determine if the program moved them properly. 
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Sample Program 

LOC +0 +2 +4 +6 +8 SOURCE STATEMENT ADDIO ,EDX002 

0000 0008 D7D9 D6C7 D9C1 D440 INSURE PROGRAM ST,DS=((ACTTAB,EDX40) , (ACTOUT,EDX40)) 















COPY 


STOREQU 


00B8 










ST 


EQU 


* 


0OB8 


00B9 


04B4 


0000 


0000 


0101 


GETST6 


HOLD,TYPE=ALL 


O0C2 


805C 


02A8 


0001 






MOVE 


US AND, 1 


00C8 


035C 


0000 


04C0 






MOVE 


#1,H0LD+$STORMAP 


O0CE 


809C 


OOEC 


00OA 






DO 


10 


O0D4 


00B9 


04B4 


02A8 


01E4 


0300 


SWAP 


HOLD , USANO , ERROR=SWAPERR 


O0DE 


8158 


0000 


4000 


0320 




MOVE 


(+MENTBL,#1),C' ',(800, BYTE) 


O0E6 


8032 


02A8 


0001 






ADD 


USANO, 1 


O0EC 


009D 


0000 


0001 






ENDDO 




00 F2 


8020 


04 FA 


0001 


0000 


220E READ 


READ 


DSl, MORTAL, 1,END=ST0P 


0OFC 


0032 


0156 












0100 


OOBl 


02AE 


04 FA 


0002 


0080 


C0NVTD 


CNTRYC,CNTRY,PREC=S,F0RMAT=(2,0,I) 


O10A 


035C 


0000 


04C0 






MOVE 


#1,HOLD+$ST0RMAP 


0110 


00B9 


04B4 


02AE 


01E4 


0300 


SWAP 


HOLD , CNTRYC , ERR0R=SWAPERR 


OllA 


OOBl 


02AC 


04FC 


0002 


0080 


CONVTD 


AGEC,AGE,PREC=S,F0RMAT=(2,0,I) 


0124 


035C 


0002 


02AC 






MOVE 


#2,AGEC 


012A 


8338 


0002 


0004 






MULT 


#2,4 


0130 


0F32 


0000 


0002 






ADD 


#1,#2 


0136 


00A3 


0502 


02A6 


014A 




IF 


(SEX, EQ, ONE, BYTE) 


013E 


015B 


0000 


04FE 


0004 




MOVE 


(+MENTBL,#1) ,RATE, (4, BYTES) 


0146 


0OA0 


0152 








ELSE 




014A 


015B 


0190 


04FE 


0004 




MOVE 


(+WMNTBL,#1) ,RATE, (4, BYTES) 


0152 












ENDIF 




0152 


00AO 


00 F2 








GOTO 


READ 


0156 










STOP 


EQU 


* 


0156 


805C 


02A8 


0001 






MOVE 


USANO, 1 


015C 


035C 


0000 


O4C0 






MOVE 


#1,H0LD+$ST0RMAP 


0162 


809C 


01A8 


OOOA 






DO 


10 


0168 


0OB9 


04B4 


02A8 


01E4 


0300 


SWAP 


HOLD , USANO , ERROR=SWAPERR 


0172 


045B 


02B4 


0000 


0190 




MOVE 


OUTAREA, (+MENTBL,#1) , (400, BYTES) 


017A 


8020 


02B4 


0002 


0000 


3110 


WRITE 


DS2,0UTAREA,2,0,END=E0FILE,ERR0R=WRERR 


0184 


0072 


01B2 


0274 










018A 


045B 02B4 


0190 


0190 




MOVE 


OUTAREA, (+WMNTBL,#1) , (400, BYTES) 


0192 


8020 


02B4 


0002 


0000 


3110 


WRITE 


DS2, OUTAREA, 2, 0,END=EOFILE,ERROR=WRERR 


019C 


0074 


01B2 


0274 










01A2 


8032 


02A8 


0001 






ADD 


USANO, 1 


01A8 


O09D 


0000 


0001 






ENDDO 




OlAE 


OOAO 


02A2 








GOTO 


END 


01B2 










EOFILE 


EQU 


* 


01B2 


8026 


2A2A 


7C5C 


5C40 


C1C3 


PRINTEXT '0** ACTUARIAL FILE HAS EXCEEDED ... 



fi" 
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O1E0 


O0A0 02A2 


01E4 




G1E4 


005C 02AA 05FA 


01 EA 


80A2 02AA 021 A 


Q1F2 


8026 2423 7C5C 5C40 C9D5 



GOTO END 
SWAPERR EQU * 

MOVE TASKRC, INSURE 
IF (TASKRC, EQ,1) 
PRINTEXT '0** INVALID UNMAPPED STORAGE ... 



021A 
021 A 
0222 



802A 02AA 0002 0244 
8026 lElD 7C5C 5C40 E2E6 



ENDIF 

IF (TASKRC, EQ, 2) 
PRINTEXT '0** SWAP AREA NOT INITIALIZED' 



0244 
0244 
024C 



80 A2 02 AA 0064 0270 
8026 201F 7C5C 5C40 D5D6 



ENDIF 

IF (TASKRC, EQ, 100) 
PRINTEXT '@** NO UNMAPPED STORAGE SUPPORT' 



0270 
0270 
0274 
0274 



0OAO 02A2 

8026 2626 7C5C 5C40 C4C9 



WRERR 



ENDIF 

GOTO END 

EQU * 

PRINTEXT '@** DISK WRITE ERROR ON ACTUARIAL 



029E 


OOAO 


02A2 










GOTO 


END 


02A2 












END 


EQU 


* 


02A2 


0022 


FFFF 










PROGSTOP 




02A6 


Fl 










ONE 


DATA 


cr 


02A7 


















02A8 


0000 










USANO 


DATA 


F'O' 


02AA 


0000 










TASKRC 


DATA 


F'O' 


02AC 


0000 










AGEC 


DATA 


F'O' 


02AE 


0000 










CNTRYC 


DATA 


F'O' 


02B0 


0000 


0200 


0000 


0000 


0000 


OUTAREA 


BUFFER 


512, BYTES 


02 BA 


0000 


0000 


0000 


0000 


0000 








04AE 


0000 


0000 


0000 












04B4 


0000 


ClCl 


0000 


0000 


0000 


HOLD 


STORBLK 


TW0KBLK=1 



0000 
0000 
04 F6 
0500 

04 FA 
04FC 
04FE 
0502 

05 FA 
0692 



0000 0100 0000 0000 0000 
0000 0000 0000 0000 0000 



0000 0000 0000 0234 0000 



MENTBL 


EQU 





WMNTBL 


EQU 


MENTBL+300 


MORTAL 


BUFFER 


256, BYTES 


CNTRY 


EQU 


MORTAL 


AGE 


EQU 


MORTAL+2 


RATE 


EQU 


MORTAL+4 


SEX 


EQU 

ENDPROG 

END 


MORTAL+8 
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Using Return Codes to Diagnose Problems 



This section describes how to use the return codes to diagnose problems. 



Many EDL instructions return a code to indicate whether or not they execute 
successfully. Each time EDX executes one of these instructions, it stores a code, 
called a return code, in the first two words, called task code words, of the task 
control block (TCB). You can access the TCB by referencing the task name. 

In the following example, the instructions at label ERRTEST compare the return 
code of the READTEXT instruction with the successful return code (-1). 

BEGIN PROGRAM START 



READTEXT NAME, ' ENTER NAME: ' ,SKIP=4,M0DE=LINE 

ERRTEST MOVE TASKRC, BEGIN 

IF (TASKRC, NE,-1), GOTO, CHECK 
ENDIF 



CHECK PRINTEXT 'ERROR IN READING NAME',SKIP=1 
PRINTNUM TASKRC 
GOTO END 



END PROGSTOP 
TASKRC DATA F'O" 

ENDPROG 

END 






You must test the return code before executing any other instruction because the 
system may overlay the task code word with the return code of the next instruction. 
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Diagnosing Errors with ACCA Devices 

To diagnose an error that occurs after you read or write to an ACCA device, you 
can use the following instructions to obtain the return code and three cycle steal 
status words. 

TEST PROGRAM START, TERMERR=TERROR 



COPY CCBEQU 



TERROR TCBGET RETCD,$TCBCO 
TCBGET #1,$TCBCCB 
MOVE CCS,($CCBSTW0,#1),3,FKEY=0 



RETCD DATA F ' ' 
CCS DATA 3F'0' 



Q Obtain the return code from the first word of the TCB. 
Q Obtain the address of the CCB (terminal control block). 
01 Move the three cycle steal status words to CCS. 

If the return code is not — 1 , the task code word contains the following information: 
Bit Description 









Unused 


1-8 
9 


ISB of last operation (I/O 

complete) 

Unused 


10 


1 if error reported as attention 
interrupt 


11 


1 if a write or control operation 
(I/O complete) 



12 Read operation (I/O complete) 

13-15 Condition code + 1 after I/O start 
or condition code after I/O 
complete 

Refer to the appropriate hardware description manual for a description of the cycle 
steal status words and the interrupt status byte (ISB) condition codes. 
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Task Error Exit Routines 

This section describes the facilities provided by the system when an exception occurs. 
These are the supervisor facihty and the system-supphed task error exit routine. 

When an exception occurs, the supervisor takes certain actions. What action it takes 
depends on whether or not you have coded a task error exit routine in your 
program. If your program does not have a task error exit routine, the supervisor 
simply writes a program check message on $SYSLOG and terminates the program. 
If your program has a task error exit routine, either the one supplied by the system 
or your own, the supervisor does the following: 

1 Stores the hardware status at the time of the exception in a block of storage 
designated by the task. 

2 Passes control to the task at its task error exit entry point. 

At this point, the task error exit routine gains control. The next section discusses 
only the system-supplied routine. However, remember that, if necessary, you can 
substitute your own routine. (For information on writing your own task error exit 
routine, refer to the Customization Guide.) 

Notes: 

1 . A task error exit routine is a part of the task it serves. The supervisor passes 
control to it at the task level; it is not a subroutine of the supervisor's error 

handler. /f"^ 

2. The registers (including the EDL software registers, #1 and #2) used by the error \^ 
exit routine are those normally used by the task. 

3. To resume executing the task following corrective action by task error exit, 
branch (if in Series/ 1 instruction mode) or GOTO (if in EDL mode) the 
appropriate location. 

4. If the error exit is unable to recover from the exception, it should issue a 
PROGSTOP instruction. 

The System-Supplied Task Error Exit Routine ($$EDXIT) 

A task error exit routine named $$EDXIT is available on volume ASMLIB. This 
routine: 

• Captures relevant data from the program header, task control block, and 
hardware status area when an exception occurs 

• Formats and prints this data on SSYSLOG and SSYSPRTR 

• Displays an error message on the loading terminal. 



o 
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To use the supplied routine, you must: 

• Code $$EDXIT as the value of the ERRXIT keyword parameter of each 
PROGRAM and TASK statement in your program. For example: 

AB PROGRAM . . . . ,ERRXIT=$$EDXIT 



CD TASK ....,ERRXIT=$$EDXIT 
• Declare the label $$EDXIT to be an EXTRN. 
EXTRN $$EDXIT 

The task error exit routine is included in the autocall hst $AUTO on volume 
ASMLIB. It is included automatically when you hnk edit any program that 
references $$EDXIT. A separate INCLUDE statement is not required for $$EDXIT 
in the LNKCTRL data set. All you need to do is code $AUTO,ASMLIB as the 
autocall data set on the AUTOCALL statement of SEDXLINK. 

The following example shows what $$EDXIT prints on $SYSLOG and SSYSPRTR. 
It shows that a program check has occurred in an application program named 
PCHECK. The numbers to the left of both columns correspond to the explanations 
that follow the example. For additional information on interpreting program check 
messages refer to the Problem Determination Guide. 

***************************************** 

* WARNING!! AN EXCEPTION HAS OCCURRED!! * 
***************************************** 



B 
Q 
B 



PROGRAM NAME 


= 


PCHECK 


m 


PSW = 8002 




PROGRAM VOLUME 


= 


EDXWRK 




lAR = 3124 




PROGRAM LOAD POINT 


= 


0000 




AKR = 0440 




ADDRESS OF ACTIVE TCB 


= 


016C 




LSR = O0DO 




ADDRESS OF CCB 


= 


1802 




RO (WORK REGISTER) 


= 0096 


NUMBER OF DATA SETS 


= 


1 


i 


Rl (EDL INSTR ADDR) 


= 00E7 


NUMBER OF OVERLAYS 


= 





R2 (EDL TCB ADDR) 


= 01 6C 


$TCBADS 


= 


0004 




R3 (EDL OPl ADDR) 


= 0OE7 


ADDRESS OF FAILURE 








R4 (EDL 0P2 ADDR) 


= 00B2 


(REL. TO PGM LOAD POINT = 


0OE7 


m 


R5 (EDL COMMAND) 


= 0000 


DUMP OF FAIL ADDRESS 








R6 (WORK REGISTER) 


= 0000 


00E6: 0000 0028 0028 


3635 






R7 (WORK REGISTER) 


= 0000 


$TCBCO = -1 DEC; 


FFFF HEX 




#1 = 0000 




$TCB02 = DEC; 


0000 HEX 




#2 = 0000 





PSW ANALYSIS: 

SPECIFICATION CHECK 
TRANSLATOR ENABLED 



€% 

^pf 
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Explanation: 

Q The PROGRAM NAME field identifies the name of the active program. 

B The PROGRAM VOLUME field identifies the name of the volume where the 
program resides. 

B The PROGRAM LOAD POINT field contains the address at which the program 
was loaded for execution. 

D The ADDRESS OF ACTIVE TCB field contains the address of the active task 
control block (TCB) when the exception occurred. 

B The ADDRESS OF CCB field contains the address of the terminal control block 
for the terminal that loaded the program. 

Q The $TCBADS field contains the address space where the program is loaded if 
not doing cross-partition move or the target address space if doing a cross-partition 
move. 

B The ADDRESS OF FAILURE field contains the address of the instruction that 
caused the program check. 

B The DUMP OF FAIL ADDRESS field shows the location and content of the 
instruction that was executing when the failure occurred. 

B The PSW field indicates the type of exception that occurred. 

[B The Rl field usually points to the EDL instruction address. 

m The Rl field usually contains the EDL TCB address. 

IB The R5 field usually contains the operation code of the EDL instruction that 
was being executed. 

The following message appears on the loading terminal when the program check 
occurs: 






A MALFUNCTION HAS OCCURRED -- CALL SYSTEM PROGRAMMER 



Notes: 

1. If you are executing either a combination of EDL instructions and Series/1 
instructions or all Series/ 1 instructions, the registers may not contain this 
information. 

2. You can restart the program by writing your own error exit routine to reload it. 

$$EDXIT provides you with information about the program, task, and hardware 
status when an exception occurs. You can extend the capabihties of $$EDXIT so 
that it will also evaluate the information and make an appropriate response. For 
more information on writing your own task error exit routine, refer to the 
Customization Guide. 
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fy Chapter 8. Reading Data from and Writing to Screens 

The Event Driven Executive allows you to read from and write to a screen that 
appears on a terminal. A person at a terminal can supply data to a program and the 
program can display information on the terminal screen. EDX allows you to use 
two types of screens: roll screens and static screens. 

This chapter describes: 

• When to use roll screens 

• When to use static screens 

• Differences between static screens and roll screens 

• Reading from and writing to roll screens 

• Reading from and writing to static screens 

• Designing device-independent static screens 

• Reading from and writing to a 3101, 3151, 3161, 3163, or 3164 Display terminal. 

Note: The procedures for a 3151, 3161, 3163, or 3164 terminal may differ from the 
procedures for a 3101 terminal. The notations to the examples explain the 
differences in the procedures. However, the procedures in this chapter that describe 
the 3101 terminal also apply to the 3151, 3161, 3163, and 3164 terminals running in 
3101 emulation mode. 

This chapter shows how to write a program to read five data items from a screen 
and write them back to the screen. The chapter shows how to use each kind of 
screen (roll and static). 

You can generally code terminal programs using either roll or static screens. 
However, each screen offers distinct advantages for certain types of programs. 

When to Use Roll Screens 

A roll screen is similar to a typewriter. The system reads or writes data line-by-hne, 
starting with line at the top of the screen and ending with line 23 at the bottom of 
the screen. You can use roll screens to read or write a single data item. 

A program that uses roll screens usually prompts the operator for data, waits for an 
operator response, and checks the vahdity of the input data. Roll screens are best 
suited for application programs in which: 

• A simple question-and-answer dialogue occurs between program and operator. 

• A single line is sufficient for each response. 

• An incorrect response requires only a reprompt. 

• You want to use a minimum of processor storage. 

In addition, the terminal may support roll screens only. 
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Roll screen dialogue is relatively easy to code and requires little program 
preparation. You can code prompts in a tree structure where the choice of the next 
prompt depends on the reply to past prompts. 

You can print more than one line of text to introduce a prompt. For example, you 
might want to offer the choice of several programs to be loaded, each of which may 
choose to continue the dialogue at the same terminal. You can also display more 
than one line of text in a program reply. 



When to Use Static Screens 



A static screen represents a page of information. The system reads or writes an 
entire screen at once. A static screen allows a terminal operator to modify an entire 
screen image before entering the data. You can use static screens to read or write 
several data items at one time. 

Programming for static screens involves managing the entire screen as a series of 
protected and unprotected fields. A protected field is an area that contains an 
operator prompt or an input field name. It is protected from being accidentally 
changed by the operator. An unprotected field is an area that is to be filled in by the 
operator.. 

Static screens are best suited for programs in which: 

• The dialogue involves a series of full screens. 

• More than one line of response may be required. 

• You need to determine cursor position or manipulate the cursor. /f ~ 

• You need to write protected fields. '\_ 

• You need attribute characters such as bUnking and nondisplay. 

• The unprotected fields may be scattered across the screen and interspersed with 
the protected fields. 

• Many related data fields are to be entered at one time. 

• Medium to large amounts of data accompany each prompt, operator response, 
or program reply. 

You can manage static screens most easily by using the $IMAGE utility to define 
your screens. $IMAGE places the screens on direct access storage. The program 
then can read them into processor storage. $IMAGE subroutines and terminal I/O 
statements allow you to read the screen into the application program, display it at 
the terminal, position the cursor, scatter read or write unprotected fields, and wait 
for a response. 



Differences Between Static Screens and Roll Screens 

Static screens differ from roll screens in the following ways: 

• Forms-control operations that would cause a page-eject for roll screens simply 
wrap around to the top for static screens. 

• On static screens, the system performs no automatic erasure. 
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Input operations directed to static screens normally are executed immediately. 
This allows the program to read selected fields ft-om the screen after the operator 
modifies the entire display. A program can issue the WAIT KEY instruction to 
wait for the operator to respond. The operator can signal the program with the 
program function (PF) keys. 

To allow convenient operator/program interaction, QUESTION, READTEXT, 
and GETVALUE instructions which include prompt messages are executed as if 
they were directed to a roll screen (automatic task suspension for input). 

On static screens, the "at sign" character @ is a data character. On roll screens, 
it indicates a new line. 



Reading and Writing One Line at a Time 



Reading and writing a single line from a terminal screen involves reading the data 
item from a roll screen and writing or displaying the data item on the screen. 

To read and write to a roll screen: 

1 . Reserve storage for data. 

2. Read a data item. 

3. Write a data item. 

Reserving Storage for the Data 

To reserve storage for a data item that you will read, you must know its maximum 
length. To reserve storage for a text string of 30 characters, use the TEXT statement 
as follows: 

NAME TEXT LENGTH=30 

The name of the storage is NAME. The next section describes how to put a data 
item into NAME. 

Reading a Data item 

To read a data item from a roll screen, you can use either the READTEXT or 
GETVALUE instruction. The READTEXT instruction allows you to read a text 
string. The GETVALUE instruction allows you to read one or more numbers. 

To read a data item into a storage area, use the READTEXT instruction as follows: 
READTEXT NAME , ' NAME : ' , SKI P=l ,MODE=LINE 

The instruction displays the prompt NAME: and the system waits for a response. 
When the operator enters a name and presses the enter key, the system stores the 
text string in an area called NAME. 

The operand SKIP = 1 causes the system to skip one line before displaying the 
prompt. The operand MODE = LINE allows blanks in the response. Since most 
names contain at least one blank, you must code MODE = LINE to read the entire 
name. 
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Writing (Displaying) a Data item 

Writing (or displaying) a data item involves transferring the data item from storage 
to the terminal screen. You can use either the PRINTNUM or PRINTEXT 
instruction to transfer data to the terminal screen. The PRINTNUM instruction 

tJ-dxiOXVJ-O V/XXV V^JL iiJLV/AV XXU-AXXUCxO. A XIV i IVXX "^ i J^yV i XXXO tX Uv LlOxX tXdXlOlCxO d LVjVI. otxxxi^. 

To display the data item called NAME, use the PRINTEXT instruction as follows: 
PRINTEXT NAME,SKIP=3 

The operand SKIP = 3 causes the system to skip three Hnes before displaying 

NAME. 



Example 



Prompt the operator for five data items: name, address, city, state, and zip code. 
Then display the five data items. Read from and write to the terminal that loaded 
the program. 



I 



TEST 


PROGRAM 


BEG 




BEG 


EQU 


* 






READTEXT 


NAME,' NAME: 


',SKIP=1,M0DE=LINE 




READTEXT 


ADDR,' ADDRESS: 


',MODE=LINE 




READTEXT 


CITY,' CITY: 


',MODE=LINE 




READTEXT 


ST,' STATE:' 






READTEXT 


ZIP,' ZIP:' 






PRINTEXT 


NAME, SKI P=3 






PRINTEXT 


ADDR,SKIP=1 






PRINTEXT 


CITY,SKIP=1 






PRINTEXT 


ST,SPACES=1 






PRINTEXT 


ZIP,SPACES=2 






PROGSTOP 






NAME 


TEXT 


LENGTH=30 




ADDR 


TEXT 


LENGTH=30 




CITY 


TEXT 


LENGTH=30 




ST 


TEXT 


LENGTH=2 




ZIP 


TEXT 

ENDPROG 

END 


LENGTH=5 





Q Begin the program and execute the instruction at label BEG. 

01 Prompt the operator for the name and read the operator's response. Allow 
spaces in the name (MODE = LINE), skip one line (SKIP= 1), and store the 
response in NAME. 

Q Prompt the operator for the address and read the operator's response. Allow 
spaces in the name (MODE = LINE) and store the response in ADDRESS. Because 
the program writes to a roll screen, the prompt appears one line below the prompt 
for name. 

Q Display the data item in NAME. Skip three Hnes before displaying (SKIP = 3). 

01 Display the data item in ADDR. Skip to the beginning of the next line before 
displaying (SKIP =1). 

Q Display the data item in ST. Leave one blank space to the right before 
displaying (SPACES =1). 
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Executing the Example 

If you entered, compiled, link edited, and loaded the example, the system would 
issue a prompt for each data item. After entering each data item, press the enter 
key. After you enter the last data item (zip code) and press enter, the system 
displays the data items. 

After you enter all five data items, the screen might look like this: 

NAME: ROSE PETERSON 
ADDRESS: 11 CYPRESS CREEK RD. 
CITY: SAUNA 
STATE:KA 
ZIP:45367 



When you press the enter key, the program displays the name and address as 
follows: 



ROSE PETERSON 

11 CYPRESS CREEK RD. 

SAUNA KA 45367 



^(**V^ 



Note: Even though CITY is 30 characters long, the system displays only the actual 
length of the data. 



Two Ways to Use Static Screens 



Reading and writing an entire screen at once involves using static screens. The 
Event Driven Executive provides two methods to define static screens. 

The first method requires that the format of the screen be defined within the 
program. Any change to the screen requires a change to the program. 

In addition, programs that use this method are usually not device independent. In 
other words, a program that contains instructions that define a static screen may 
execute successfully on a 4978, 4979, or 4980 terminal and not execute on a 3101, 
3151, 3161, 3163, or 3164 terminal. 

The sections called "Coding the Screen within a Program" on page 8-6 and 
"Transferring an Entire Screen Image at Once" on page 8-10 describe the first 
method. 

The second method for defining screens involves defining the screen with the 
$IMAGE utihty and saving it in a data set. This method allows more than one 
program to use the same screen. In addition, a change to the screen does not 
necessarily require a change to each program that uses it. 

Finally, you can write programs that are device independent; they execute 
successfully on 4978, 4979, 4980, 3101, 3151, 3161, 3163, or 3164 terminals. For 
information on designing static screens that you can use on these terminals, see 
"Designing Device-Independent Static Screens" on page 8-24. 
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The section called "Writing the Screen Image to a Data Set" on page 8-15 describes 
the second method. 

For more information on coding static screens, see Appendix C, "Static Screens and 
Device Considerations." 



Coding the Screen within a Program 

This section describes reading data from and writing data to a static screen. 
Instructions in the program create the static screen. 

For more information on static screens, see Appendix C, "Static Screens and Device 
Considerations." 

This section describes one way to code a static screen within a program. For 
another way to define a screen within a program, see "Transferring an Entire Screen 
Image at Once" on page 8-10. 

This section focuses on a sample program, describing the instructions in the same 
sequence that they appear in the program. 

The sample program: 

1 Defines the screen as static 

2 Gets exclusive access to the terminal __ 
J Erases the screen ^-* 

4 Reserves storage for data 

5 Prompts the operator for a data item 

6 Positions the cursor 

7 Waits for a response 
O Reads a data item 
y Writes a data item. 

Defining a Screen as Static 

To define a screen as a static screen, use the lOCB statement as follows: 
TERM lOCB SCREEN^STATIC 

This statement defines the loading terminal as a static screen. The label TERM 
defines the name you will use in other instructions in the program. 



For information on defining logical screens, see Appendix C, "Static Screens and 
Device Considerations." 



^L^Jr 
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Getting Exclusive Access to the Terminal 

Before you can use a terminal as a static screen, you must get exclusive access to it. 
Use the ENQT instruction as follows: 

ENQT TERM 

The operand TERM is the name you used to define the terminal in an lOCB 
instruction. 

Erasing the Screen 

Before you code instructions that prompt the operator for data, you should erase the 
screen. To erase the screen, use the ERASE instruction as follows: 

ERASE MODE=SCREEN,TYPE=ALL,LINE=0 

The operand LINE = tells the system to begin erasing on line (the first line) of 
the screen. The operand MODE = SCREEN causes the system to erase to the end of 
the screen. The operand TYPE = ALL allows the system to erase both protected and 
unprotected data. 

Reserving Storage 

To reserve storage for a data item that you read, you must know its maximum 
length. To reserve storage for a text string of 30 characters, use the TEXT statement 
as follows: 

NAME TEXT LENGTH=30 

The name of the storage is NAME. The READTEXT instruction transfers the data 
item containing the name into this area of storage. 

Prompting the Operator for a Data Item 

One way you can display information on a static screen is by issuing PRINTEXT 
instructions. For example, to prompt the operator for a name, use the PRINTEXT 
instruction as follows: 

PRINTEXT 'NAME: ' ,LINE=1,PR0TECT=YES 

The instruction displays the prompt NAME. The operand LINE = 1 causes the 
system to display the prompt on the second line of the screen. (The lines on a screen 
are numbered — 23 and the columns are numbered — 79.) The operand 
PROTECT = YES causes the prompt NAME: to be protected. A protected field 
cannot be changed by the operator. 

Positioning the Cursor 

If you use PRINTEXT instructions to prompt the operator for several data items, 
you would probably want to position the cursor after the first prompt. To position 
the cursor, you need two instructions: a PRINTEXT instruction and a 
TERMCTRL instruction: 

PRINTEXT LINE=1,SPACES=13 
TERMCTRL DISPLAY 



^Kjjpr 
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The operands LINE = 1 and SPACES =13 cause the system to position the cursor on 
the fourteenth space of hne 1 (the second Hne). (The hnes of a screen are numbered 
through 23.) 

Since the PRINTEXT instruction actually accumulates output in the system buffer, 
the TERMCTRL instruction is required to cause the cursor to be positioned. 

Waiting for a Response 

After you issue all the prompts, you must wait for the operator to respond. To wait 
for a response, use the WAIT instruction as follows: 

WAIT KEY 

The operand KEY means that the program will wait until the operator presses either 
the enter key or one of the Program Function (PF) keys. 

Reading a Data Item 

Reading a data item involves issuing a READTEXT instruction for each data item 
you want to read. The READTEXT instruction might look hke this: 

READTEXT NAME,LINE=1,SPACES=13,M0DE=LINE 

The instruction reads the data item into the storage area called NAME. The 
operands LINE = 1 and SPACES =13 cause the system to look for the data starting 
in the fourteenth position of the second Hne of the screen. The operand 
MODE = LINE allows the data to contain blanks. 

Writing a Data item 

Writing a data item means transferring a data item from a storage area to the screen. 
A PRINTEXT instruction might look Hke this: 

PRINTEXT NAME,LINE=11 

The instruction writes the data item from the storage area called NAME. The 
operand LINE = 11 causes the system to display the data starting in the first position 
of the twelfth line of the screen. 

If you want to display another data item on the next Hne, you can use the SKIP 
operand as follows: 

PRINTEXT ADDR,SKIP=1 

The SKIP = 1 causes the system to skip to the first position of the next Hne. 

To leave spaces between one data item and another, use the SPACES operand as 
foHows: 

PRINTEXT CITY,SPACES=2 

The SPACES = 2 operand causes the system to leave two blanks between the 
previous data item and CITY. 
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Example 



Prompt the operator for five data items: name, address, city, state, and zip code. 
Then display the five data items. 



TEST 
TERM 
BEG 



i 

m 

i 



NAME 

ADDR 

CITY 

ST 

ZIP 



PROGRAM 

lOCB 

ENQT 

ERASE 

PRINTEXT 

PRINTEXT 

PRINTEXT 

PRINTEXT 

PRINTEXT 

PRINTEXT 

TERMCTRL 

WAIT 

READTEXT 

READTEXT 

READTEXT 

READTEXT 

READTEXT 

PRINTEXT 

PRINTEXT 

PRINTEXT 

PRINTEXT 

PRINTEXT 

TERMCTRL 

DEQT 

PROGSTOP 

TEXT 

TEXT 

TEXT 

TEXT 

TEXT 

ENDPROG 

END 



BEG 

SCREEN=STATIC 

TERM 

MODE=SCREEN,TYPE=ALL, 



,LINE= 
,SKIP= 
,SKIP= 
,SKIP= 
,SKIP= 



NAME 
ADDRESS 

CITY 

STATE 

ZIP 

LINE=1,SPACES=13 
DISPLAY 
KEY 

NAME,LINE=1,SPACES=13 
ADDR,LINE=2,SPACES=13 
CITY,LINE=3,SPACES=13 
ST,LINE=4,SPACES=13 
ZIP,LINE=5,SPACES=13 
NAME,LINE=11 
ADDR,SKIP=1 
CITY,SKIP=1 
ST,SPACES=1 
ZIP,SPACES=2 
DISPLAY 



LENGTH=30 

LENGTH=30 

LENGTH=30 

LENGTH=2 

LENGTH=5 



LINE=0 

1,PR0TECT=YES 

1,PR0TECT=YES 

1,PR0TECT=YES 

1,PR0TECT=YES 

1,PR0TECT=YES 



,MODE=LINE 
,MODE=LINE 
,MODE=LINE 



B Begin the program and execute the instruction at label BEG. 

Q Define the screen as static. 

Q Get exclusive use of the terminal. 

01 Erase the screen. Erase the entire screen (MODE = SCREEN), including 
protected and unprotected fields (TYPE = ALL), and begin on the first hne of the 
screen (LINE = 0). 

B Prompt the operator for name. Display the prompt on the second line of the 
screen (LINE= 1) and prevent the operator from overlaying the prompt 
(PROTECT = YES). 

Q Prompt the 'operator for address. Display the prompt one line below the 
previous prompt (SKIP = 1) and prevent the operator from overlaying the prompt 
(PROTECT = YES). 

Q Position the cursor on the fourteenth space (SPACES = 13) of the second hne of 
the screen (LINE= 1). 
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1^ Cause the cursor to be positioned (the previous PRINTEXT instruction 
accumulates output in the system buffer). 

Q Wait for the operator to respond to the prompts. Resume execution when the 
operator presses either the enter key or one of the Program Function keys. 

nSI Read the first data item. Look for the data in the fourteenth space 
(SPACES = 13) of the second hne of the screen (LINE = 1) and allow blanks in the 
data (MODE = LINE). 



Read the second data item (address). Look for the data in the fourteenth space 
(SPACES = 13) of the third Hne of the screen (LINE = 2) and allow blanks in the 
data (MODE = LINE). 



Display the data item NAME. Begin displaying the data on the first position 
of the twelfth Une of the screen (LINE =11). 

iEH Display the data item ADDR. Begin displaying the data on the first position 
of the next Une (SKIP = 1). (In this example, ADDR would appear on the thirteenth 
hne of the screen.) 



Display the data item ST. Begin displaying the data after leaving one space 
(SPACES = 1). (In this example, data item ST would appear one space to the right 
of data item CITY.) 

EQ Cause the data in ZIP to be displayed. (The data in ZIP remains in the system 

buffer until you issue this instruction or end the program with a PROGSTOP.) ^ 



IQj Relinquish exclusive use of the terminal. 



Transferring an Entire Screen Image at Once 



This section describes a technique for transferring an entire screen to the display in 
one I/O operation. 

This section shows how to: 

L Define protected and unprotected fields. 

Z Define the screen. 

J Erase the screen. 

4- Construct a screen image. 

J Read a series of data items. 

6 Release the terminal. 



\^ 
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Defining Protected and Unprotected Fields 

The format of a 4978, 4979, or 4980 screen is defined as each character is written to 
the terminal. Fields are defined as follows: 

• Each character or group of characters written with PROTECT = YES defines a 
protected field. 

• Each character or group of characters written without PROTECT = YES defines 
an unprotected field. 

• Null characters (X ' 00 ' ) can never be protected, so both protected and 
unprotected fields can be defined by writing data containing interspersed nulls 
with PROTECT = YES. 

Once the fields of a screen have been defined, the 4978, 4979, or 4980 knows 
internally whether each of the 1920 positions on the screen is protected or 
unprotected; this is transparent to the user. 

On the 4978, 4979, or 4980 there are two ways to write and read unprotected fields. 
The first is to read/write all the unprotected fields with one input/output operation. 
All the unprotected fields can be filled with data by one "scatter write" operation 
(PRINTEXT MODE = LINE). The unprotected fields can be read using one 
"gather read" operation (READTEXT MODE = LINE). The other way is to read 
or write individual fields by specifying screen coordinates (the LINE = and 
SPACES = parameters). 

Defining the Screen 

To define a screen as static, use the lOCB statement as follows: 

SCREEN lOCB SCREEN=STATIC,B0TM=11, C 

BUFFER=BUFF,RIGHTM=959 

This statement defines the loading terminal as a static screen. The label SCREEN is 
the name you will use in other instructions in the program. The operand 
BOTM = 11 defines the last usable line on the page as hne eleven (the twelfth line). 
The operand RIGHTM = 959 defines the last usable character position on the screen 
as the 959th position. The number 959 is the size of the buffer (BUFF is 960 bytes 
long) minus one. 

Erasing the Screen 

Before you code instructions that prompt the operator for data, you should erase the 
screen. Use the ERASE instruction as follows: 

ERASE TYPE=ALL,LINE=0 

The operand TYPE = ALL tells the system to erase both protected and unprotected 
data. The operand LINE = tells the system to begin erasing on line (the first 
hne) of the screen. 
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Constructing a Screen Image 

To construct a screen image that minimizes screen flicker, you can concatenate a 
series of protected fields. The following instructions display an array of integers on 
the first six Hnes of the screen (lines — 5). 

DO 96,INDEX=1 

PRINTEXT 'FIELD',PROTECT=YES 

PUTEDIT FORMATl , VALS ,((!)), PROTECT=YES 

PRINTEXT ' ■,PROTECT=YES 

PRINTEXT NULLS, PROTECT=YES 
ENDDO 

B PRINTEXT LINE=0 

Q Begin a DO loop to construct the screen image. The screen image consists of 96 
protected fields of the form FIELDxx, where xx is a sequential field number, each 
followed by one protected blank and two unprotected data positions. 

B Put the literal FIELD in the buffer. 

B Convert the sequence number to two EBCDIC characters and write it to the 
buffer. 

B Insert a protected separation character. 

B Define the data position with two null characters. Null characters generate 
unprotected fields. The operand PROTECT = YES is necessary to preserve 
concatenation. (You can concatenate a series of fields only if the fields are all 
protected (PROTECT = YES) or all unprotected (PROTECT = NO).) 

B Write the concatenated line to the screen. (Any line control character causes the 
system to display the concatenated fields.) 

Reading a Series of Data Items 

To read a series of data items, use the READTEXT instruction as follows: 
READTEXT VALS,M0DE=LINE,LINE=5 

The instruction does a "gather read," reading all the values beginning on hne 6 (the 
seventh Hne) of the screen into VALS. The operand MODE = LINE indicates the 
gather read. 

Releasing the Terminal 

To release the terminal, use the DEQT instruction: 
DEQT 

The instruction releases the buffer designated in the lOCB statement and restores the 
configuration to that defined by the TERMINAL statement. 
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Example 



Line-oriented input/output instructions provide a straightforward way to construct 
and read data from static screens. However, when individual data fields on the 
4978, 4979, or 4980 are accessed frequently, excessive screen flicker can result. This 
problem can be eliminated by transferring an entire screen image to the display with 
one I/O operation. The following program shows this technique. 



The program accesses the top six lines of a static screen and initially formats the 
screen with a sequence of protected fields. An array of integers is displayed on Unes 
— 5 of the screen and a pause is executed to allow the operator to enter a new set 
of values in corresponding positions of lines 6—11. The new values are then 
displayed on lines — 5 of the screen. 









In this program, terminal I/O operations are performed through concatenation of 
TEXT strings. If the application requires more complex formatting of the screen 
image, or if input of more than 254 bytes at a time is necessary, then direct access to 
the buffer is appropriate. See the PRINTEXT and READTEXT instructions in the 
Language Reference for details. 



DISPLAY 


PROGRAM 


BEGIN 


Q SCREEN 


lOCB 


SCREEN=STATIC,B0TM=11, 




BUFFER=BUFF,RIGHTM=959 


I 


DATA 


F'O' 


1 BUFF 


BUFFER 


960, BYTES 


NULLS 
NUMS 


DATA 


X'0202' 


DATA 


X'OOOO* 


DATA 


48F'0' 


VALS 


TEXT 


LEN6TH=254 


BEGIN 


ENQT 


SCREEN 


ERASE 


TYPE=ALL,LINE=0 




DO 


96,INDEX=I 




PRINTEXT 


'FIELD',PROTECT=YES 


1 


PUTEDIT 


FORMATl, VALS, ( (I) ),PROTECT=YES 


1 


PRINTEXT 


' ',PROTECT=YES 


^ ; 


PRINTEXT 


NULLS, PROTECT=YES 




ENDDO 




IS 


PRINTEXT 


LINE=0 


iS WRITE 


PUTEDIT 


F0RMAT1,VALS,((NUMS,48)), 




ACTION 


=STG 




PRINTEXT 


VALS,MODE=LINE,LINE=0 




PRINTEXT 


LINE=6,SPACES=8 




TERMCTRL 


DISPLAY 




WAIT 


KEY 


• 


GOTO 


(TRANSFER, QUIT), DISPLAY+2 


1 1 TRANSFER 


READTEXT 


VALS,M0DE=LINE,LINE=6 


i 


GETEDIT 


F0RMAT1,VALS,((NUMS,48)), 




ACTION=STG 


i 


ERASE 


LINE=6,M0DE=SCREEN,TYPE=DATA 


X 


GOTO 


WRITE 


11 QUIT 


DEQT 
PROGSTOP 




FORMATl 


FORMAT (12) 




ENDPROG 






END 





Q Define the static screen with the terminal I/O buffer to be in the appHcation 
program at BUFF, with a length of 960 bytes (half of the 4979 display screen). 
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Write the concatenated line to the display. Any convenient line control 
operation or the DEQT instruction will accomphsh this. 

Q] Convert the integer array to two-character EBCDIC values and store the 
resulting hne in the TEXT buffer VALS. 

09 Write the values into successive unprotected positions of the display beginning 

at LINE = 0, SPACES = 0. This "scatter write" operation is defined by 

MODE = LINE; without MODE = LINE the protected fields of the display would be 

overwritten. 

B3 Define the cursor to be at the first unprotected position. 

[Q Display the cursor at its defined position. 

B3 Wait for the operator to press an interrupt key. 

[Q Go to QUIT if PFl was pressed. Go to TRANSFER if the ENTER key or 

any key other than PFl was pressed. 



\^ 



Qj Allocate storage for the buffer. Note that in this program the buffer is never 
accessed directly; the space is merely allocated here for use by the supervisor. 

Q and Q Define a TEXT message consisting of two null characters (EBCDIC 
code X' 00'). 

01 and Q Define the array of integers (initially zero) and the TEXT buffer that 
will be used for output of the data in EBCDIC form. 

Q and Q Acquire the terminal, erase all data and establish the screen position for 
the first I/O operation. Since several text strings will be concatenated to form the 
first output line, the screen position must be established in advance. 

Q Begin a DO loop to construct the initial screen image. This will consist of 96 
protected fields of the form FIELDxx, where xx is a sequential field number, each 
followed by one protected blank and two unprotected data positions. Note the 
conditions required for forming a concatenated line: the protect mode of the 
PRINTEXT instructions must not change (either all PROTECT = YES or all 
PROTECT = NO), and no intervening forms control operations can be executed. 
The TERMCTRL DISPLAY instruction prints the contents of the terminal buffer. 

B Write "FIELD" to the buffer. 

ffol Convert the sequence number to two EBCDIC characters and write it to the 
buffer. 

Q Write a protected separation character. /^"^ 

IM Write the two null characters to define the data positions. Null characters 
always generate unprotected positions on the screen; however, PROTECT = YES is 
required here in order to maintain concatenation. 
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1^ Read the updated values entered by the operator in Hnes 6 — 11. 
MODE = LINE indicates a "scatter read." 

CT Convert the EBCDIC representations to binary and store the binary values in 
the array NUMS. 

1^ Erase the unprotected (data) fields in hnes 6 — 11 of the screen. 

03 Repeat beginning at the label WRITE. 

Q] Release the terminal. The buffer designated in the lOCB will be released and 
the screen configuration restored to that defined by the TERMINAL statement. 



Writing the Screen Image to a Data Set 



This section shows how to create a screen image and use it in a program. The 
approach assumes that you want to write a program that can execute on different 
terminals. 

For information on writing terminal-independent static screens, see "Designing 
Device-Independent Static Screens" on page 8-24. For more information on writing 
a screen image to a data set, see Appendix C, "Static Screens and Device 
Considerations." 

Writing a screen to a data set and using it in a program requires that you do the 
following things: 

1 Create the screen. 

2 Define the screen as static. 

J Read the screen into a buffer. 

4 Get exclusive access to the terminal. 

J Display the screen and position the cursor. 

6 Reserve storage for data. 

7 Wait for a response. 
O Read a data item. 
y Write a data item. 

10 Link edit the program. 
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Creating a Screen 



To create a screen image, use the $IMAGE utility as follows: 

1 From the session manager, select option 4 (TERMINAL UTILITIES) from 
the primary option menu. 

2 Then select option 4 ($IMAGE). This option loads the $IMAGE utihty. 

J Define a null character when the COMMAND(?) prompt appears by entering: 

COMMAND (?): NULL # 



You will use the null character to define unprotected fields. Unprotected fields 
are the fields in which the operator will enter data. 

4 Define the screen dimensions as 24 by 80 (full screen) by entering: 



COMMAND (?): DIMS 24 80 



5 Enter the command EDIT. A blank screen appears. 

O Press the PFl key to enter define protected fields mode. While in define 
protected fields mode, you can define the screen. 

7 Enter the text for your screen image. Enter the fixed part of the screen exactly 
as you want it to appear on the screen. The fixed fields are called protected 
fields. Use the null character (#) to define the unprotected data fields. 

An example of how the screen might look follows: 






J 



NAME: ##M####i#########i########### (line 1) 

ADDRESS: ############################## (line 2) 

CITY: ############################## (line 3) 

STATE: ## (line 4) 

ZIP: ##### (line 5) 



O Press the enter key after you complete the design of your screen image. The 
enter key takes you out of define mode. 

V Press the PF3 key to return to the $IMAGE command mode. 
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10 Save your new screen image in data set AP08CSCR on volume EDX002 by 
% entering: 

SAVE APQ8CSCR,EDXO02 



11 In response to the message: 

SHOULD THE 31XX INFORMATION BE SAVED (Y/N)? 



reply N if you want to save only a 4978/4979/4980 screen image. Reply Y to 
this message if you are using the ATTR command of $IMAGE to define a 
31xx screen image. Refer to the Operator Commands and Utilities Reference 
for details on the ATTR command of $IMAGE. 

Note: A 31xx screen image is used for a 3101, 3151, 3161, 3163, or 3164 
terminal in block mode. 

12 After the system saves the screen, use the EN command to end the $IMAGE 
utihty. 

For more information on creating a screen image, refer to the Language Reference. 






Defining the Screen as Static 

To define a screen as static, use the lOCB statement as follows: 

TERM lOCB SCREEN=STATIC, X 

BUFFER=IOBUF, X 

OVFLINE=YES, X 

LEFTM=0, X 

RIGHTM=79, X 

TOPM=0, X 
B0TM=23 

This statement defines the loading terminal as a static screen. The label TERM 
defines the name you will use in other instructions in the program. The BUFFER 
operand identifies lOBUF as the buffer that will be associated with the screen. The 
OVFLINE operand tells the system to continue a line that exceeds the right margin 
on the next line. The next four operands (LEFTM, RIGHTM, TOPM, and BOTM) 
define the static screen as the entire physical screen (Unes 0-23 and columns — 79). 

Note; Remember that to continue a Une, the continued hne must begin in column 
16. 

For information on defining logical screens, see Appendix C, "Static Screens and 
Device Considerations." 
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Reading the Screen Image into a Buffer 

To read the screen you have created, you need to do the following things: 

1 Code the name and volume of the screen in a TEXT statement: 

DSNAME TEXT 'AP08CSCR,EDXG02' 

This TEXT statement refers to data set AP08CSCR on volume EDX002. This 
data set contains the screen you saved when you used the $IMAGE utility. 

2 Reserve storage for the screen with a BUFFER statement: 

DISKBFR BUFFER 1024, BYTES 

The amount of storage you reserve depends on how many bytes $IMAGE 
used to store the screen image. For example, if SIMAGE used 900 bytes to 
store a screen image, use 1024 bytes (the next highest 256-byte increment). See 
"Coding for Device Independence" on page 8-26 for more information about 
calculating additional buffer requirements for $IMAGE for the 3101, 3151, 
3161, 3163 and 3164 terminals. 

J Specify the type of image data set you have created or specify four blank 
characters for the data stream of the terminal type: 

TERMTYPE DATA C 

The type of image data set refers to the way you stored the data set. The 
system always saves a 4978/4979/4980 screen image. You may, however, 
choose that the system also save 31xx screen information. 

Note: A 3Ixx screen image is used for a 3101, 3151, 3161, 3163, or 3164 
terminal in block mode. 

4 Use the CALL instruction to read the screen: 

CALL SIMOPEN, (DSNAME) , (DISKBFR) , (TERMTYPE) 

The SIMOPEN subroutine reads the screen from the data set defined by 
DSNAME and puts the screen into DISKBFR. TERMTYPE refers to the 
DATA statement that defines the type of image data set. 

Getting Exclusive Access to the Terminal 

Before you can use a terminal as a static screen, you must get exclusive access to it. 
Use the ENQT instruction as follows: 

ENQT TERM 

The operand TERM is the name you used to define the terminal in the lOCB 
instruction. 
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Displaying the Screen and Positioning the Cursor 

Displaying the screen and positioning the cursor involves three instructions. 

The first instruction, the CALL $IMPROT instruction, prepares the protected fields 
for display: 

CALL $IMPROT,(DISKBFR),(FTABLE) 

The presence of the third operand (in this case, FTABLE) causes the instruction to 
construct what is called a field table, h field table shows the location and length of 
each unprotected field on the screen. Define the field table as follows: 

FTABLE BUFFER 15, WORDS 

The field table requires 3 words for each unprotected field. 

The second instruction positions the cursor after the first prompt: 
PRINTEXT LINE=1,SPACES=9 

Finally, the third instruction displays the screen: 
TERMCTRL DISPLAY 

Reserving Storage for Data 

To reserve storage for a data item that you read, you must know its maximum 
length. To reserve storage for a text string of 5 characters, use the TEXT statement 
as follows: 

ZIP TEXT LENGTH=5 

The name of the storage is ZIP. This storage area will eventually contain five bytes 
of data in our example (the zip code). 

Waiting for a Response 

After you issue the prompts, you must wait for the operator to respond. To wait for 
a response, use the WAIT instruction as follows: 

WAIT KEY 

The operand KEY means that the program will wait until the operator presses either 
the enter key or one of the Program Function (PF) keys. 
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Reading a Data Item 

Reading a data item involves reading all unprotected data from the screen. Use the 
READTEXT instruction as in the following example: 

READTEXT IOBUF,MODE=LINE,LINE=0,SPACES=0 

The instruction reads all unprotected data into the buffer called lOBUF. The 
operands LINE = and SPACES = cause the system to look for the data starting in 
the first position of the screen. MODE = LINE allows for blanks in the input data. 

To move each data item into its own storage area, use the following instructions: 

MOVEA #1,I0BUF 

MOVE NAME, (0,#1), (30, BYTE) 

The MOVEA instruction moves the address of lOBUF which contains the 
unprotected fields. The MOVE instruction moves the 30 bytes at the start of the 
buffer to NAME. 

For each additional field, increment register 1 to the next field in lOBUF and move 
the field to its data area: 

ADD #l,FTABLE+4 

MOVE ADDR,(0,#1),(30,BYTE) 

The ADD instructions adds the size of the first field (NAME) to register 1 . The 
MOVE instruction moves the 30 bytes at lOBUF + 30 to ADDR. 

Writing a Data Item 

Writing a data item means transferring a data item from a storage area to the screen. 
A PRINTEXT instruction might look Hke this: 

PRINTEXT NAME,LINE=11 

The instruction writes the data item from the storage area called NAME. The 
operand LINE= 11 causes the system to display the data starting in the first position 
of the twelfth line of the screen. 

If you wanted to display another data item on the next line, you could use the SKIP 
operand: 

PRINTEXT CITY,SKIP=1 

The SKIP = 1 causes the system to skip to the first position of the next hne before 
displaying the data item CITY. 

To display another data item on the same line, you could use the SPACES operand: 
PRINTEXT ST,SPACES=1 

SPACES = 1 causes the system to skip one space on the same line before displaying 
the data item ST. 



o 



o 
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Link Editing the Program 

Using the $IMAGE subroutines ($IMOPEN, $IMDEFN, $IMPROT, and 
SIMDATA) means that you must do one more thing when you link edit the 
program. You must reference the $IMAGE subroutines you have used. An 
EXTRN statement must be coded for each subroutine name your program 
references. 

You must supply the linkage editor, SEDXLINK, the following "control 
statements": 

AUTOCALL $AUTO,ASMLIB 
INCLUDE ASM0BJ,EDX002 
LINK APO8C,EDX40 REPLACE END 

The first control statement refers to a library of IBM-supphed routines. Unless you 
have moved the library, you can code this statement as you see it here. 

The second control statement refers to where you put the output of the compiler. 

The third control statement says to put the output of the link edit on volume 
EDX40, call it AP08C, and replace it if it already exists. END tells SEDXLINK not 
to expect any other control statements. 

You can either create a data set containing these control statements or enter the 
statements "interactively" each time you execute SEDXLINK. 

For more information on Hnk editing, see Chapter 5, "Preparing an Object Module 
for Execution." 



Chapter 8. Reading Data from and Writing to Screens 8-21 



Reading Data from and Writing to Screens 



Example 



Prompt the operator for name, address, city, state, and zip code. Then display the 
five data items. Use the screen AP08CSCR on volume EDX002 (already defined 
with the SIMAGE utility). 



I 
I 



TEST PROGRAM BEG 

EXTRN $IMOPEN,$IMDEFN,$IMPROT,$IMDATA 
TERM lOCB SCREEN=STATIC, 

BUFFER=IOBUF,OVFLINE=YES,LEFTM=G, 
RIGHTM=79 , TOPM=0 , BOTM=23 
BEG CALL $IMOPEN,(DSNAME),(DISKBFR),(TERMTYPE) 
MOVE C0DE,TEST+2 
IF C0DE,NE,-1 
PRINTEXT 'OPEN ERROR CODE = •,SKIP=1 
PRINTNUM CODE 



i 

m 





GOTO 


END 




ENDIF 






ENQT 


TERM 




CALL 


$IMPROT, (DISKBFR), (FTABLE) 




PRINTEXT 


LINE=1,SPACES=9 




TERMCTRL 


DISPLAY 




WAIT 


KEY 




READTEXT 


IOBUF,MODE=LINE,LINE=0,SPACES=0 




MOVEA 


#1,I0BUF 




MOVE 


NAME, (0,#1), (30, BYTE) 




ADD 


#l,FTABLE+4 




MOVE 


ADDR, (0,#1), (30, BYTE) 




ADD 


#1,FTABLE+10 




MOVE 


CITY, (0,#1), (30, BYTE) 




ADD 


#1,FTABLE+16 




MOVE 


ST,(0,#1),(2,BYTE) 




ADD 


#l,FTABLE+22 




MOVE 


ZIP,(0,#1),(5,BYTE) 




PRINTEXT 


NAME,LINE=11 




PRINTEXT 


ADDR,SKIP=1 




PRINTEXT 


CITY,SKIP=1 




PRINTEXT 


ST,SPACES=1 




PRINTEXT 


ZIP,SPACES=2 




DEQT 




END 


PROGSTOP 




DSNAME 


TEXT 


'APO8CSCR,EDX002' 


DISKBFR 


BUFFER 


1024, BYTES 


TERMTYPE 


DATA 


C'4978' 


FTABLE 


BUFFER 


15, WORDS 


lOBUF 


BUFFER 


1920, BYTES 


CODE 


DC 


F'G' 


NAME 


TEXT 


LENGTH=30 


ADDR 


TEXT 


LENGTH=30 


CITY 


TEXT 


LENGTH=30 


ST 


TEXT 


LENGTH=2 


ZIP 


TEXT 

ENDPROG 

END 


LENGTH=5 
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Q Begin the program and execute the instruction at label BEG. 

Q Define as external references the $IMAGE subroutines that the program uses. 
The linkage editor resolves these external references when you use the autocall 
option. 

01 Define the screen as static. 

Q Read the screen from the data set defined by DSNAME. Put the screen in the 
buffer defined by DISKBFR. 

Q Move the return code that resulted from the SIMOPEN subroutine to CODE. 

13 If the return code that resulted from the SIMOPEN subroutine does not indicate 
"successful completion," display an error message and end the program. 

Q Get exclusive use of the terminal. 

Q Prepare the protected fields for display. 

Q Position the cursor on the tenth space (SPACES = 9) of the second hne of the 
screen (LINE = 1). 



[Q Display the 



screen. 



Wait for the operator to respond to the prompts. Resume execution when the 
operator presses either the enter key or one of the Program Function keys. 



Read all unprotected data. Look for the data in the first space (SPACES = 0) 
of the first Hne of the screen (LINE = 0) and allow blanks in the data 
(MODE = LINE). 

IB! Move the address of the buffer (lOBUF) that contains the unprotected data 
into register 1 . 

Move the first 30 characters from the buffer to NAME. 

Increment register 1 to point to the next data item (address). 

ni Display the data item NAME. Begin displaying the data on the first position 
of the twelfth hne of the screen (LINE =11). 



Display the data item ADDR. Begin displaying the data on the first position 
of the next hne (SKIP = 1). (In this example, ADDR would appear on the thirteenth 
hne of the screen.) 

JTI Display the data item ST. Begin displaying the data after leaving one space 
(SPACES = 1). (In this example, data item ST would appear one space to the right 
of data item CITY.) 

Itl Point to the data set (AP08CSCR on volume EDX002) that contains the screen 
created with the $IMAGE utihty. 
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B»l Reserve storage for the screen. (Except for screens much larger than the one in 
this example, 1024 bytes is enough storage.) 

Ql Define the type of image data set to be read. C ' 4978 ' allows you to write the 
screen to a 4978, 4979, 4980, 3101, 3151, 3161, 3163, or 3164 terminal, regardless of 
what screen image was saved on disk. C'310r allows you to write the screen to a 
3101 terminal if you saved the 31xx screen image. C'3161 ' allows you to write the 
screen to a 3151/3161 if you saved the 31xx screen image. C'3163' allows you to 
write the screen to a 3163 if you saved the 31xx screen image. C'3164' allows you 
to write the screen to a 3164 if you saved the 31xx screen image. If you code C 
' , you can write the screen to whatever terminal has been enqueued. 

[^ Reserve storage for the field table. 

Bel Reserve storage for the unprotected data. 



Designing Device-Independent Static Screens 

The following sections mention both the $IMAGE utiHty and the $IMAGE 
subroutines. For a complete description of the $IMAGE utility, refer to the 
Operator Commands and Utilities Reference. For descriptions of the $IMAGE 
subroutines, see "$IMAGE Subroutines" on page C-3. 

Designing Static Screens 

This section describes how to design terminal independent static screens and 
discusses a Hmitation in compatibility between the terminal types. 

The $IMAGE utility and subroutines treat an unprotected field as a string of 
unprotected characters. Unprotected characters are denoted as null characters. If 
the SIMAGE null character were the "percent sign" character, (%), then an 
unprotected field, eight characters long, could be defined as: 

ENTER NAME HERE ==> %%%%%%%% 

If you do not place attribute characters around an unprotected field, SIMAGE 
automatically inserts the default attribute in 31xx screen images for the 3101, 3151, 
3161, 3163, and 3164 terminals. Refer to the Operator Commands and Utilities 
Reference for information on the characteristics of the default attribute. If you do 
not want to define unique attributes (such as Winking), you can design screens for 
the 4978, 4979, or 4980 and use them on 3101, 3151, 3161, 3163, and 3164 terminals 
with default attributes. 






\j 
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You can also design 31xx screens with unique attribute characters. In this case, a 
31xx screen image is created by $IMAGE as well as a 4978/4979/4980 image. The 
31xx information is ignored for display on the 4978, 4979, or 4980. If the "pound 
sign" character ,(#), were defined as the blinking attribute, both fields in the 
previous example could be made to blink as follows: 

#ENTER NAME HERE ==> #%%%%%%%@ 

On a 3101, 3151, 3161, 3163, or 3164, a blinking, protected attribute byte would 
replace the first pound sign and a Winking, unprotected attribute byte would replace 
the second pound sign. The pound sign does not change the protect status of the 
field, merely its display properties; the "null" character determines whether the field 
is protected or unprotected. The screen could be reset to nonbUnking by placing the 
default attribute (in this case, @) at the end of the protected field. 

Compatibility Limitation 

This scheme has a limitation because an attribute byte is displayed as a protected 
blank. This character, the attribute byte, which precedes a field (protected or 
unprotected) is always displayed as a blank on a 3101, 3151, 3161, 3163, or 3164 
terminal, even if a protected (nonblank) character appears on a 4978, 4979, or 4980. 
For example, the following screen is designed to display the month, day, and year as 
MM/DD/YY: 



On a 4978, 4979, or 4980, the date would appear as: 
10/30/80 

On a 3101, 3151, 3161, 3163, or 3164, however, the date would appear as: 
10 30 80 

The slash characters on the 4978, 4979, or 4980 are replaced by attribute bytes on 
the 3101, 3151, 3161, 3163, and 3164. Therefore, screens designed for the 4978, 
4979, or 4980 do not have to be changed for use on the 3101, 3151, 3161, 3163, and 
3164. However, you have to alter them if you do not want protected characters to 
disappear when displayed on a 3101, 3151, 3161, 3163, or 3164. 
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Coding for Device Independence 

To achieve static screen device independence between the 4978, 4979, or 4980 
Display Terminal and the 3101, 3151, 3161, 3163, and 3164 Display Terminal, you 
must use functionally equivalent terminal instructions on the terminals. The 
following considerations show one approach v/hich provides some device 
independence. 

• Use the 4978/4979/4980 screen images produced by $IMAGE for 4978, 4979, 
4980 and 3101, 3151, 3161, 3163, 3164 compatible applications. 

• Specify an image type of C 4978 ' on calls to $IMOPEN. 

• Specify FTAB on calls to SIMPROT. The FTAB buffer is initiaHzed to describe 
each unprotected field on the screen and requires three words per entry. 

• Use calls to $IMDATA to "scatter write"the unprotected data to either type 
terminal. 

PRINTEXT MODE = LINE does not produce a scatter write operation on the 
3101, 3151, 3161, 3163, or 3164 (as it does on the 4978, 4979, or 4980). A call 
to $IMDATA, specifying the FTAB produced by the prior call to SIMPROT 
and the user buffer, performs the scatter write operation on the 4978, 4979, or 
4980 and simulates the scatter write on the 3101, 3151, 3161, 3163, or 3164. 

$IMDATA can be used to write either default unprotected data from the screen 
image or user data contained in a user buffer. 

• For "gather read" operations use: 

READTEXT MODE=LINE,TYPE=DATA,LINE=0,SPACES=0 

Read operations from the 3101 running in block mode start with the first data r \ 

field encountered, beginning with the upper left corner and continuing to the end \^ 

of the screen. Specifying LINE - 0,SP ACES = makes the READTEXT from 
the 4978, 4979, or 4980 functionally equivalent to the 3101 running in block 
mode. 

On the 3151, 3161, 3163, and 3164 terminals, if the first position of the screen is 
unprotected, unpredictable results will occur when reading the screen. To 
achieve static screen independence, ensure that the first character position on the 
screen is protected from operator input. The first character should be either an 
attribute character or a protected data character on the 3151, 3161, 3163, or 
3164, never a null character. 

In addition, the 3101 prefixes each field transmitted with three bytes of control 
information; this results in a 3101 data stream. The 3151 and 3161 prefixes each 
field transmitted with four bytes of control information; this results in a 3161 
data stream. The 3163 and 3164 prefix each field transmitted with six bytes of 
control information; this results in a 3164 data stream. Although EDX removes 
this control information, the user buffer must be large enough to contain the 
entire data stream that is transmitted. 
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Using care, individual fields can be changed with: 
PRINTEXT MODE=LINE,LINE= ,SPACES= 

- When issued to a 3101, 3151, 3161, 3163, or 3164, the PRINTEXT 
instruction first writes an attribute byte, followed by the text data. The data 
field thus appears displaced one position to the right when compared to the 
result of a PRINTEXT issued to the 4978, 4979, or 4980. 

To suppress the writing of an attribute byte to the screen, use: 
TERMCTRL SET,ATTR=NO 

prior to the PRINTEXT(s). After the last PRINTEXT, code TERMCTRL 
SET,ATTR-YES. The 4978, 4979, and 4980 ignore these TERMCTRL 
instructions. 

- Be careful to ensure that the data being sent to the 3101, 3151, 3161, 3163, 
or 3164 does not extend beyond one data field; if it does, it will overlay and 
ehminate existing attribute characters. Once the screen attributes are 
changed, the FTAB no longer represents the screen and $IMDATA 
operations will produce undesired results. 

- Writing protected nulls to create additional unprotected 4978, 4979, or 4980 
fields is not supported for the 3101, 3151, 3161, 3163, or 3164 running in 
block mode. Avoid this practice. 

Avoid the combination of "count" and TYPE = DATA in the ERASE 
instruction. On the 3101, 3151, 3161, 3163, or 3164, the erase starts at the 
current cursor position and continues to the end of screen; the count operand is 
ignored. 

Avoid the combinations of TYPE = DATA,MODE = LINE and 
TYPE = DATA,MODE = FIELD in the ERASE instruction. Although these 
combinations work as anticipated on the 4978, 4979, or 4980, the 3101, 3151, 
3161, 3163, and 3164 force the MODE- parameter to SCREEN. 

Avoid the combination of "count," TYPE = ALL and MODE = FIELD in the 
ERASE instruction. The 3101, 3151, 3161, 3163, and 3164 force 
MODE = FIELD to MODE = LINE. The operation ends when the count 
reaches zero or the current line ends, whichever occurs first. 

To erase unprotected fields that do not end at end-of-line or end-of-screen, use 
one of the following techniques: 

- Use a PRINTEXT instruction with LINE and SPACES parameters to write 
blank characters to each individual field, being careful not to change or 
eliminate 3101, 3151, 3161, 3163, or 3164 attribute bytes. 

Note: If the screen attributes are changed or eliminated, then the screen 
format will no longer match the FTAB and the data will not be directed to 
the correct locations on the screen. To re-establish the screen, call 
$IMPROT before calling SIMDATA. 

- Use READTEXT TYPE = DATA to read all unprotected data from the 
screen into a user buffer. Next, blank out (or change) the appropriate fields 
in the buffer. Then use the "USER" buffer features of SIMDATA to 
rewrite the unprotected data. 
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Using the $IMAGE Subroutines for Device independence 

This section presents a way to write terminal-independent applications that use static 
screens. Using this method, the $IMAGE utihty creates screen images and stores 
them on disk or diskette. Later, your application program can display and use the 

xi.xj.u.^W/0 L/V v/ClxxXxj.^ o y oi.wxiA~k/JL V ViVAX-'^j. oiA-i^x \j txi.xxj.wd. x^v/xxww Lx V vx y VXXVOW Ol4.l_/X V w-uxxxwo cXxv^ 

called the "$IMAGE subroutines." See "$IMAGE Subroutines" on page C-3 for 
individual descriptions of each subroutine. 

This section describes the basic steps in an application program which displays and 
processes a static screen (with a size of 24 Hues and 80 characters per hne): 

• Retrieve the screen 

• Display the protected data 

• Display and retrieve the unprotected data. 

Retrieving the Screen Format 

The first step is to retrieve the screen image by calhng $IMOPEN. The type 
operand of $IMOPEN specifies the type of image to be retrieved. If the type 
operand is set to blanks, the image retrieved corresponds to the type of terminal 
upon which the program is running, if that image was saved. If a particular screen 
image is needed but unavailable, the 4978/4979/4980 format is retrieved and 
converted dynamically. For example: 

CALL $IMOPEN, (DSNAME) , (FORMAT) , (TERMTYPE) 






DSNAME TEXT 


LENGTH=15 


format data set name 


FORMAT BUFFER 


n, BYTES 


format buffer 


TERMTYPE DATA 


CL4' 


adapt to running terminal 






Displaying the Protected Data 

The screen format itself (the protected data) can be displayed with a call to 
SIMPROT. 

CALL $ IMPROT , ( FORMAT) , ( FTAB) 

FTAB BUFFER n, WORDS field table 

The field table (FTAB) is required for the 3101, 3151, 3161, 3163, and 3164 
terminals. For a description of the field table, see "$IMPROT Subroutine" on 
page C-8. 



8-28 SC34-0943 



i-/' 



Reading Data from and Writing to Screens 



Displaying tlie Unprotected Data 

At this point many applications generate and then display some data in the 
unprotected fields. On a 4978, 4979, or 4980 you can use PRINTEXT 
MODE = LINE to perform a scatter write operation. However, since this is not 
supported on a 3101, 3151, 3161, 3163, or 3164, you should use $IMDATA to 
perform the scatter write operation and thus preserve device independence. 

$IMDATA writes all the unprotected fields in a screen image. You must call 
SIMDATA if any of your unprotected fields have the right justify or must enter 
characteristics. When directing data to the 3101, 3151, 3161, 3163, or 3164, the field 
table generated by $IMPROT must be used. To write default unprotected data, use 
the buffer containing the screen image or specify a user buffer containing the 
apphcation-provided data. 

When $IMDATA is used with a user buffer, the application program must: 

• Set the characters "USER" in the first four positions of the buffer 

• Set the message length, excluding "USER", in the buffer index word (buffer — 4). 

MOVE USERDATA.CUSER, DWORD set up user message 

MOVE DATALEN,8 set message length 

MOVE USERDATA+4, MESSAGE, (8, BYTES) get message 

CALL $IMDATA,(USERDATA),(FTAB) 



USERDATA BUFFER 12, BYTES, INDEX=DATALEN for user data 
MESSAGE DATA CLB'HI THERE' data 

CUSER DATA CL4'USER' 

Retrieving the Unprotected Data 

After the operator has entered data, all the data in the unprotected fields can be read 
by a single statement. The 4978, 4979, 4980, 3101, 3151, 3161, 3163, and 3164 
support a "gather read" using READTEXT MODE = LINE. 

READTEXT SCRNDATA,MODE=LINE 



SCRNDATA BUFFER n, BYTES 

There are a number of considerations when using a READTEXT with 

MODE = LINE and a buffer from a 3101 screen. A READTEXT instruction issued 

to the 3101 always reads from the beginning of the screen, regardless of the cursor 

position specified by LINE and SPACES. The 3101 has only three read options: 

read the entire screen (TYPE = ALL), read all the unprotected fields 

(TYPE === DATA), or read only the modified unprotected data 

(TYPE = MODDATA). (For more information on 3101 read options, see "Reading 

Modified Data on the 3101" on page 8-42). 
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The data will be read and concatenated into the buffer. But the buffer must be large 
enough to accommodate the data. On the 3101, the buffer must accommodate the 
data plus three bytes (TYPE = DATA and TYPE = ALL) or four bytes 
(TYPE = MODDATA) per unprotected field. On the 3151, 3161, 3163, and 3164 
terminals, the buffer must be large enough to accommodate the data plus four bytes 
(TYPE = MODDATA) per unprotected field. On the 3151 and 3161, the buffer must 
accommodate the data plus four bytes (TYPE = DATA and TYPE = ALL) per 
unprotected field. On 3163 and 3164, the buffer must accommodate the data plus 
six bytes (TYPE == DATA and TYPE = ALL) per unprotected field. This extra data 
includes escape sequences and attribute bytes which are edited out of the buffer 
before presentation to the appHcation program (as long as the default of 
STREAM = NO is in effect). 

Although the 4978, 4979, and 4980 terminals have the capabihty to read a specific 
unprotected field, the 3101, 3151, 3161, 3163 and 3164 do not. To perform a similar 
operation, the appHcation can read all the unprotected data and then use the field 
table lengths to displace into the buffer and arrive at the desired data field. 

Suppressing Attribute Bytes 

The 4978, 4979, 4980, 3101, 3151, 3161, 3163, and 3164 terminals can do a 
PRINTEXT with LINE and SPACES to a specific screen coordinate. However, 
issuing this instruction on the 3101, 3151, 3161, 3163, or 3164 affects subsequent I/O 
to the screen. When a PRINTEXT is issued without a previous TERMCTRL 
SET,ATTR = NO, the terminal support inserts an attribute byte. This attribute byte 
appears as a protected blank at the screen coordinate specified by LINE and 
SPACES, and the data follows. Normally, this displaces the data one byte to the 
right, and therefore the data writes over the next attribute byte (which usually 
describes a protected field). 

For example, assume the screen coordinate 5,5 (LINE = 5, SPACES = 5) contains a 
ten-byte unprotected field which the apphcation wants to fill with ten Xs. If a 
PRINTEXT LINE = 5,SPACES = 5 of ten Xs is issued with no previous 
TERMCTRL SET,ATTR = NO, then an attribute byte is added and written at 
location 5,5 and the tenth X overwrites the next attribute byte for the following 
protected field. This leaves the screen with one large unprotected field instead of a 
10 byte unprotected field followed by a protected field. 

A subsequent READTEXT of the unprotected data will result in much more data 
being returned to the application than expected. In addition, the returned data 
stream might contain escape sequences and attribute bytes which on a subsequent 
PRINTEXT from the same buffer will cause the cursor to act unpredictably. Also, 
the data will be written incorrectly on the screen. 

To avoid such problems, a TERMCTRL SET, ATTR = NO should always be issued 
before a PRINTEXT with LINE and SPACES. A TERMCTRL SET,ATTR = YES 
should follow the PRINTEXT. 



\ 



^%,(jir 



8-30 SC34-0943 






Reading Data from and Writing to Screens 



Converting 4978 Screens 

Many 4978-based applications can be converted to run on the 3101, 3151, 3161, 
3163, or 3164. In some cases, it is sufficient to convert uses of PRINTEXT 
MODE = LINE to calls to SIMDATA. If the appHcation uses READTEXT to 
specify screen coordinates with LINE and SPACES, the technique described above 
in "Suppressing Attribute Bytes" can be used. 

Some screens may require changes because the attribute bytes are displayed as 
protected blanks on the 3101, 3151, 3161, 3163, and 3164. See the "Compatibihty 
Limitation" on page 8-25. 



Reading and Writing to a 3101, 3151, 3161, 3163, or 3164 

This section describes how to read data from and write data to a 3101, 3151, 3161, 
3163, or 3164 Display Terminal. It describes the characteristics of these terminals 
and some things you should know when you design programs that use these 
terminals. 

This section focuses on a sample program, describing the instructions in the same 
sequence that they appear in the program. The sample program uses a 3101 
terminal, the TERMCTRL instruction to set attribute bytes, and EBCDIC escape 
sequences to control data transmission. Wherever similarities exist, notations for the 
3151, 3161, 3163, and 3164 terminals have been made. The sample program, which 
appears at the end of this chapter: 

I Defines the format of the screen 

J Enqueues the screen 

J Change the attribute byte 

4 Erases the screen 

5 Protects the first field 

O Creates unprotected fields 
7 Creates protected fields 
O Writes a nondisplay field 
" Reads a data item 
10 Writes a bhnking field 
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11 Erases an individual field 

12 Blanks a blinking field \^ 
IJ Writes more than one data item 

1 4 Prompts the operator for data 

15 Changes the attribute byte to a protected blank 
jfO Displays a nondisplay field 

1 7 Creates a new unprotected field 

lo Reads modified data 

ly Forces the modified data tag on 

2iJ Reads modified data 

21 Erases to the end of the screen 

22 Reads all unprotected data 
2 J Reads a data item. 

Characteristics of the Terminal ^*^ 

Attribute Characters 

The 3101, 3151, 3161, 3163, and 3164 terminals use attribute characters (or bytes) to 
define fields on the screen. An attribute byte defines the start of each field and the 
properties of the field (such as high/low intensity, underline, or Wink). Each 
attribute byte appears as a protected blank on the screen. 

The collection of attribute characters, special sequences required by the terminal, and 
user data is called a data stream. Any invalid (unprintable) characters encountered 
in the data stream will cause the terminal to beep. This condition might occur, for 
instance, if you try to display a non-EBCDIC disk or diskette record. The message 
"HOST PROGRAM WRONG" is issued if any invalid (unprintable) characters are 
encountered in the 3151, 3161, 3163, or 3164 data stream. 



Transmitting Data 



On a static screen, the application program must determine where the output data is 
positioned, relative to the first position of the screen. When you issue a 
READTEXT instruction on a 3101, the system reads the data from the beginning of 
the screen. Whether you read all the data, unprotected data, or modified data 
depends on how you code the TYPE operand of the READTEXT instruction. See 
"Coding for Device Independence" on page 8-26 for more information about using 
the READTEXT instruction on the 3151, 3161, 3163, and 3164 terminals. 
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In response to a read request, the 3101, 3151, 3161, 3163, and 3164 terminals 
transmit the attribute characters that precede the input field. To suppress the 
attribute characters from the data stream, EDX removes these special characters and 
left-justifies the data. 

An application program can have complete control of the input/output data 
transmitted. To do this, the program must build the complete data stream, either in 
EBCDIC or ASCII codes. The basic terminal I/O support simply handles the 
transmission of the data stream. 

Refer to the description of the TERMCTRL SET,STREAM= YES/NO instruction 
and the XLATE parameter of PRINTEXT/READTEXT instructions in the 
Language Reference when this mode of data transmission is desired. 

Design Considerations 

The following hst contains items you should consider when designing a static screen 
appUcation. 

• Each of the 3101, 3151, 3161, 3163 and 3164 terminals uses a different data 
stream to tell the terminal to do something. A data stream is a collection of 
special characters, commands, and data transmitted in a single operation. 

• A simple PRINTEXT of "HI THERE" results in a data stream appropriate for 
the terminal that is running. 

On the 3101: ESC. Y. ROW. COL. ESC. 3. ATTR. HI THERE 

On the 3151/3161: ESC.Y.R0W.C0L.ESC.3.PA1.PA2.HI THERE 

On the 3163/3164: ESC.Y.R0W.C0L.ESC.3.PA1.PA2.PA3.PA4.HI THERE 

where ESC.Y is a set cursor address command followed by row and column 
position, and ESC. 3 is a start-of-field sequence followed by one or more 
attribute bytes defining the field. 

• An attribute byte defines how data will appear on the screen. It occupies one 
character position on the screen and appears as a protected blank. Note that a 
start-of-field sequence containing multiple attribute bytes will require only one 
character position on the screen. 

• Special attribute characteristics supported by the 3101 are high intensity, low 
intensity, blinking field, and nondisplay. The 3151, 3161, 3163, and 3164 
terminals support these special attributes with the TERMCTRL instruction, in 
addition to other attributes through the $IMAGE utihty. Refer to the IBM 
3151 ASCII Display Station Reference Manual, GAl 8-2634, IBM 3161/3163 
ASCII Display Station Description, GAl 8-23 10 and the IBM 3164 ASCII Color 
Display Station Description, GAl 8-23 17 for a hsting of all the attributes 
available for your terminal. 
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Use the TERMCTRL SET,ATTR= instruction or the ATTR command of 
SIM AGE to set the attribute bytes for the 3101. Use the ATTR command of 
SIM AGE to set attribute bytes for the 3151, 3161, 3163, and 3164 terminals. 

If an attribute is not required on the 3101, code a TERMCTRL 
SET,ATTR = NO before coding a PRINTEXT to a specific location. 

Unprotected static screen read operations for a block mode 3101 terminal start 
with the first data field encountered and continue to the end of the screen. The 
first data field encountered is in the upper left corner (row 1, column 1). The 
first data field for the 3151, 3161, 3163, and 3164 terminals in block mode, 
however, may be wrapped. In other words, the data field beginning in the upper 
left corner is considered by the terminal to be the last or part of the last 
unprotected field in the screen for all read operations. The 3151, 3161, 3163, 
and 3 1 64 terminal read operations read data from this field into the buffer 
following all other unprotected fields in the screen. Apphcations performing 
read operations should always, therefore, compensate for wrapped fields when 
reading from the 3151, 3161, 3163, and 3164 block mode terminals. 

To prevent the wrapping of unprotected fields, design screen images so that the 
first character position is either a protected character or an attribute character, 
never an unprotected character. 

Escape sequences take up space in the buffer. Therefore, it takes more than 
1920 bytes to read a complete screen. Data streams for the 3151, 3161, 3163, 
and 3164 require more space than those for the 3101. The 3151 and 3161 
require one additional byte per field and the 3163 and 3164 require three 
additional bytes per field. Ensure that the buffer is larger enough to hold all the 
data. 

The terminal type and the TERMCTRL SET ATTR= and STREAM = 
parameters determine the number of bytes required in the buffer. For example, 
a PRINTEXT instruction could require a buffer length equal to the data length 
plus ten times the number of fields. A READTEXT instruction could require a 
buffer length equal to the data length plus six times the number of fields when 
TYPE = ALL and TYPE -DATA. 

The following table hsts the number of bytes needed in the buffer, in addition to 
the data length. 



^ 



Instruction 


3101 


3151/3161 


3163/3164 


PRINTEXT 


7x#of 
fields 


8x#of 
fields 


10 X # of 
fields 


READTEXT 


3x#of 
fields 


4x#of 
fields 


6x#of 
fields 



Figure 8-1. Additional Buffer Requirements 

A READTEXT instruction requires a buffer length equal to the data length plus 
four times the number of fields when TYPE = MODDATA. 



o 
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• A READTEXT TYPE = DATA reads all unprotected data. If 

MODE = WORD, fields are separated by blanks. If MODE = LINE, fields are 
concatenated. 

• A WAIT KEY prior to a READTEXT TYPE = MODD ATA should be satisfied 
with a PF key and not the SEND key. If MODE- WORD, fields are separated 
by blanks. If MODE = LINE, fields are concatenated. 

• A READTEXT without a prompt transmits data from the beginning of the 
screen, regardless of the cursor position. 

• After the SEND key is pressed, an RDCURSOR returns as the cursor position 
the first position of the next Une. If a PF key is pressed, it does not move the 
cursor. 

Defining the Format of the Screen 

A screen format is a representation of the protected fields on a screen. References to 
the 3101 Display Terminal in this section mean a 3101 model 2x operating in block 
mode as used in the sample program. 

Like the 4978, 4979, or 4980, the format of a 3101, 3151, 3161, 3163, or 3164 screen 
is defined by how the data is written, either protected or unprotected. However, on 
the 3101, 3151, 3161, 3163, and 3164, the field definitions are not transparent to the 
user because attribute bytes separate protected and unprotected fields. 

• An attribute byte defines the start of each field and the properties of the field. 

• Each field continues until another attribute byte is encountered. 

• Each attribute byte occupies one character position on the screen and is 
displayed as a protected blank preceding the field. 

• Attribute bytes are Uke any other character on the screen in that they can be 
overwritten by data or another attribute byte. When an attribute byte is 
overwritten, the screen format can change. 

On a 3101, 3151, 3161, 3163, and 3164, you cannot do a scatter write with a 
PRINTEXT instruction; however, you can specify screen coordinates on output 
(PRINTEXT LINE-, SPACES = ). You can do a gather read by specifying 
READTEXT MODE = LINE. However, the input of a specific field (by means of 
READTEXT LINE = , SPACES = ) always executes as though LINE = and 
SPACES = had been coded. 

As a result of these differences, writing terminal independent code using the 
READTEXT/PRINTEXT instructions can be difficult. However, you can use 
$IMAGE to perform terminal independent input/output. 

Enqueuing the Screen 

The sample program must enqueue the 3101 to change the function to static screen. 
The screen size is forced to 24 x 80 and a CCB buffer is used. The CCB buffer size 
is terminal dependent; the 3101 requires 203 bytes, the 3151 and 3161 require 201 
bytes, and the 3163 and 3164 require 200 bytes. 

lOCBl lOCB SCREEN=STATIC 



ENQT lOCBl 

Chapter 8. Reading Data from and Writing to Screens 8-35 



Reading Data from and Writing to Screens 

Changing the Attribute Byte 

On the 3 101, the default attribute is high intensity. After it is changed, the sample d^\ 

program always restores the default attribute to high intensity. \^ 

TERMCTRL SET,ATTR=LOW 

Erasing the Screen 

Erasing the screen defaults the count to 1920 for the 3101 used in the sample 
program. 

ERASE TYPE=ALL 

Protecting the First Field 

In the sample program, the first field defined is a protected field at 0,0. This ensures 
that the whole screen will be formatted and that no unformatted data areas will be 
returned on whole screen reads, whether the read is TYPE = ALL, TYPE = DATA or 
TYPE = MODD ATA. 

Printing the null character (defined in the DATA statement ATTRBUTE) with 
STREAMING in effect with LINE/SPACES causes EDX to: 

• Generate the set cursor address sequence to the LINE/SPACES specified 

• Generate the start field sequence, including the current attribute which will 
create or cause an attribute at LINE/SPACES to be rewritten. 

The 3101 data stream is shown below; the attribute byte is shown as "#". 
ESC.Y.R0W,C0L.ESC.3.#.X'00' 

The null data is required to force the start field sequence; however, a null character 
is ignored by the 3101. 

DATA X'OlOr DUMMY TEXT STATEMENT CNT=1 L6TH=1 

ATTRBUTE DATA X'OQOG" NULL TO FORCE ATTRIBUTE TO WRITE 



PRI NTEXT ATTRBUTE , LI NE=0 , SPACES=0 , PR0TECT=YES 
TERMCTRL SET,ATTR=HIGH RESTORE ATTRIBUTE 

The code shown above would apply also for the 3151, 3161, 3163, and 3164 
terminals, if the following data streams are used: 

On the 3151/3161: ESC.Y.ROW.COL.ESC.3._.C.X'0O' 
On the 3163/3164: ESC.Y.R0W.C0L.ESC.3._#. ! .@.X'00' 
where _ represents a blank. 



^toM«»- 
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Creating Unprotected Fields 

To create unprotected fields on the screen ("holes" in which the operator can enter 
data), the sample program starts each field with an unprotected attribute byte and 
ends it with a protected attribute byte. 

PRINTEXT ATTRBUTE,LINE=4,SPACES=29 



TERMCTRL SET,ATTR=LOW 

PRINTEXT ATTRBUTE,LINE=4,SPACES=34,PR0TECT=YES 

Creating Protected Fields 

The next step is to create protected field descriptions. This could be done with 
ATTR = NO since the screen is already defined as protected in these areas. The 
sample program, however, uses a standard PRINTEXT to write a protected attribute 
byte at LINE/SPACES, followed by the Hteral data. 

PRINTEXT HEAD1,LINE=1,SPACES=20,PROTECT=YES 

PRINTEXT 'ENTER A NUMBER' ,LINE=4,SPACES=2,PR0TECT=YES 

Writing a Nondisplay Field 

The sample program uses a field description which is not initially displayed on the 
screen. To create a nondisplay field, set the attribute to blank. 

NONDISP TERMCTRL SET,ATTR=BLANK 

PRINTEXT 'ENTER ANOTHER NUMBER' ,LINE=12,SPACES=2,PR0TECT=YES 
TERMCTRL SET,ATTR=HIGH RESTORE ATTRIBUTE 

Reading a Data Item 

Two EDL instructions that have an impUed wait are: 

• READTEXT with prompt 

• GETVALUE with prompt. 

The LINE and SPACES parameters of these instructions specify the position of the 
attribute byte of the unprotected prompt field. Printing a null prompt field positions 
the attribute byte and cursor differently than for a prompt which is data. For 
example: 

Normal GETVALUE = #pronipt#_ 

Null prompt GETVALUE = #_ 

NULPRMPT TEXT LENGTH=0 USED ON IMPLIED WAIT INSTRUCTIONS 



GETVAL GETVALUE FIELDING, NULPRMPT, LINE=4,SPACES=29 
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Writing a Blinking Field 

The sample program also uses a protected blinking field. 

BLINK TERMCTRL SET,ATTR=BLINK 

PRINTEXT 'FIELDl MUST BE EVEN ' ,LINE=2,SPACES=5,PR0TECT=YES 
TERMCTRL SET,ATTR=HI6H RESTORE ATTRIBUTE 

Erasing an Individual Field 

The sample program erases individual fields using the erase end-of-field/end-of-hne 
function. To do this, an ESC. I is sent as data. The field to be erased is specified by 
LINE/SPACES, and the current attribute byte is rewritten followed by the ESC. I. 
The data stream on the 3101 follows: 

ESC. Y. ROW. COL. ESC. 3. #. ESC. I 



DATA X'02Q2' ERASE END OF FIELD 

ERASEFLD DATA X'27C9' ESC. I 



ERASEF PRINTEXT ERASEFLD, LINE=4,SPACES=29 

To erase a field, do an ERASE with a count value equal to the field length + 1 and 
TYPE = ALL. The + 1 is for the unprotected attribute. 

ERASEF2 ERASE 5,TYPE=ALL,LINE=4,SPACES=29 ERASE FLDl 

Blanking a Blinking Field ^^ 

Once an even number is entered, the bhnking field is blanked out by changing the 
attribute byte to nondisplay. 

TERMCTRL SET,ATTR=BLANK 

PRINTEXT ATTRBUTE,LINE=2,SPACES=5,PR0TECT=YES 

Writing More Than One Data Item 

In the sample program using a 3101, a horizontal tab character is inserted between 
fields to simulate a scatter write. This is done using PUTEDIT; however, you could 
also use the CONCAT instruction or indexed moves. The 3101 data stream is 
shown below. X ' 05 ' represents an EBCDIC horizintal tab character. 

ESC.Y.R0W.C0L.ESC.3.#.DATA1.HT.DATA2 

DATA X'OlOl' HORIZONTAL TAB 
TAB DATA X'0500' TAB TO NEXT FIELD 



SCATTER PUTEDIT F0RMAT1,TEXT0UT, (AS,TAB,BS) ,LINE=6,SPACES=29 



FORMATl FORMAT (A15,A1,A15) ,PUT 

TEXTOUT TEXT LENGTH=31 SIZE OF DATA STREAM 
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Prompting the Operator for Data 



The sample program uses a standard QUESTION instruction. 



QUEST QUESTION 'WANT TO SEE MORE ?' ,NO=ENDIT,LINE=10,SPACES=5 



An invalid response to a QUESTION (anything other than Y or N) is handled by 
the supervisor, which reissues the read. This results in a string of two new fields: a 
question mark and a response field. 

#PROMPT#?#?#?#?#_ 

Changing the Attribute Byte to a Protected Blank 

To clear this string of fields, you could overwrite them with a protected field of 
blanks. Instead, the sample program finds each field and changes the attribute to 
blank protected. 

RDCURSOR LINE, SPACES FIND CURSOR 
PRINTEXT LINE=LINE,SPACES=SPACES 

TERMCTRL DISPLAY FORCE SOFT CURSOR ADDRESS 
* TO BE UPDATED 

DO UNTIL, (SPACES, EQ, 5), AND, (LINE, EQ, 10) 






A backtab command is sent as data to position the cursor in the first position of the 
unprotected field preceding the current cursor address. SET,ATTR==NO is used to 
prevent EDX from generating the attribute byte and preceding start field sequence. 
The 3101 data stream follows: 

ESC. 2 



BACKTAB 



DATA 
DATA 



X'0202' 
X'27F2' 



BACK TAB TO FIRST CHARACTER 
POSITION OF NONPROTECTED FIELD 



TERMCTRL SET,ATTR=NO 

PRINTEXT BACKTAB 

RDCURSOR LINE, SPACES FIND NONPROTECTED FIELD CURSOR 

IS IN 
SUB SPACES,! ADJUST TO ATTRIBUTE BYTE 

TERMCTRL SET,ATTR=BLANK PREPARE TO BLANK IT 
PRINTEXT ATTRBUTE,LINE=LINE,SPACES=SPACES,PROTECT=YES 
ENDDO 
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Displaying a Nondisplay Field 

Now the sample program displays the nondisplay field previously discussed (ENTER 

ANOTHER NUMBER). The attribute that is currently blank protected is rewritten .^ ^ 

to low protected. 

LIGHT TERMCTRL SET,ATTR=LOW 

PRINTEXT ATTRBUTE,LINE=12,SPACES=2,PR0TECT=YES 

Creating a New Unprotected Field 

Next the sample program creates a new unprotected field with the cursor in place; 
this is useful for data entry. To create an unprotected field on demand with the 
cursor in place, write the end-of-field attribute first and then the start of field 
attribute. 

CREATEU TERMCTRL SET,ATTR=LOW 

PRINTEXT ATTRBUTE,LINE=12,SPACES=34,PR0TECT=YES 
TERMCTRL SET,ATTR=HIGH RESTORE ATTRIBUTE 
PRINTEXT ATTRBUTE,LINE=12,SPACES=29 
WAIT KEY 

Reading Modified Data 

A read of modified data has several implications: 

• A field is modified by entering data or erasing the field. The modified data tag 
(MDT) in the attribute byte is turned on by the 3101, 3151, 3161, 3163, and 
3164 terminals. 

• The modified data tag could be on when the attribute byte is written. SIMAGE 

provides this capabihty. f ^, 



• Group 2, switch 4 on the 3101 enables the SEND key to function as the SEND 
LINE key. When the SEND key is pressed, the data that is on the same Une as 
the cursor is sent. The type of data that is sent depends on the type of read in 
effect, namely all data, unprotected or modified. 

• Once a modified field is sent to the Series/ 1 through the SEND key or a read 
buffer, the modified data tag in the attribute byte is turned off 

At this point during the sample program execution, another number (FIELD4 data) 
has been entered and the SEND key has been pressed. The cursor was probably on 
the same hne as FIELD4; if it was, FIELD4 data was sent to satisfy the WAIT 
KEY and the modified data tag was turned off A subsequent READTEXT of 
TYPE = MODDATA would not return FIELD4 unless the cursor were moved to a 
hne not containing modified fields, or a PF key were used to satisfy the WAIT 
KEY. 

To read only the fields in which numbers were entered, the sample program rewrites 
the attribute bytes for those two fields with the modified data tags on. Before the 
modified fields are read, there is an intervening write, so the program locks the 
keyboard. 

TERMCTRL LOCK 

TERMCTRL SET,ATTR=NO TO WRITE MDT ON ATTRIBUTE 



\^ 



^fciUuUJll*^ 
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Forcing the Modified Data Tag On 

A start field sequence with an unprotected, high intensity attribute (with MDT on) is 
written as data. The 3101 data stream follows: 

ESC. Y. ROW. COL. ESC. 3. E 



SETMOD 



DATA 
DATA 
DATA 



X'0303' 
X'27F3' 
X'C5O0' 



TO FORCE MODIFIED DATA TAG ON 
START FIELD SEQUENCE 
ATTRIBUTE=HIGH, UNPROTECTED, MDT ON 



PRINTEXT SETMOD, LINE=12,SPACES=29 
PRINTEXT SETMOD, LINE=4,SPACES=29 

The data streams for the 3151, 3161, 3163 and 3164 are longer because more 
parameters are needed to indicate the attribute: 

On the 3151/3161: ESC.Y.R0W.C0L.ESC.3. (.A 



DATA X ■ 0404 ' 

SETMOD DATA X'27F3' 

DATA X'4DC1' 



TO FORCE MODIFIED DATA TAG ON 
START FIELD SEQUENCE 
ATTRIBUTE=HIGH, UNPROTECTED, MDT ON 



SETMOD 



On the 3163/3164: ESC.Y.R0W.C0L.ESC.3. (. ! .$.0 



TO FORCE MODIFIED DATA TAG ON 
START FIELD SEQUENCE 
ATTRIBUTE=HIGH, UNPROTECTED, MDT 



DATA 


X'06O6' 


DATA 


X'27F3' 


DATA 


X'4D5A5B7C' 



Now the sample program issues a READTEXT with TYPE = MODD ATA; this 
reads all the modified data on the screen, in this case two fields. 

READMOD READTEXT MTEXT,TYPE=MODDATA,MODE=LINE 

IF (MTEXT,NE,MTEXT+4,4) PSEUDO TESTING 



MTEXT 



TEXT 



LENGTH=8 



READ OF MODDATA: STREAM 
LENGTH = DATA + (4*N0FLDS) 



16 
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Reading Modified Data on tlie 3101 

On the 3101, 3151, 3161, 3163, and 3164, an unprotected field is considered to be a 
modified field when: 

• Any character within the field is changed by the operator 

• Certain ERASE instructions are executed 

• The modified data tag (MDT) in the attribute byte is on. 

The modified data tags are reset when the data is read by a READTEXT 
TYPE = MODDATA instruction or transmitted by pressing the SEND key. To 
return a protected field using READTEXT TYPE = MODDATA, design the field 
with the modified data tag set on in the attribute byte. 

To read all the modified fields fi-om a screen, the operator must position the cursor 
on a protected line which does not contain any modified fields. If the cursor is not 
on such a hne and the operator presses the enter key to satisfy a WAIT KEY 
instruction, the MDTs on that Hne are reset. A subsequent READTEXT would 
therefore not return to the program the modified data on that line. If a PF key 
instead of the SEND key is used to satisfy the WAIT KEY, the MDTs are not 
changed. 

The lOCB BUFFER = parameter or the CCB buffer must be large enough to 
contain the received 3101, 3151, 3161, 3163, or 3164 data stream prior to the editing 
of the ESC sequences. If the CCB buffer is not large enough, use the lOCB buffer. 

Erasing to the End of the Screen ,r~\ 

To prepare to erase the remaining fields, the sample program positions the cursor to (4 J 

the second field. 

PRINTEXT LINE=6,SPACES=29 
TERMCTRL DISPLAY 

Using ERASE with TYPE = DATA, all the unprotected fields from the current 
cursor position to the end of screen are erased. The count value is not used and 
mode is forced to screen. 

ERASUNP ERASE TYPE=DATA ERASE REMAINING UNPROTECT FIELDS 
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Reading All Unprotected Data 

The sample program uses GETEDIT to get all the unprotected fields under format 
control. You could also use a READTEXT without a prompt; this would read all 
the unprotected data from the start of the screen. 

6ETALL GETEDIT F0RMAT2,TEXTAMT, (N01,ALPH1,ALPH2,N02) 



TEXTAMT TEXT 



F0RMAT2 FORMAT 



LENGTH=38 GETEDIT STREAM LENGTH = 
DATA + (3*N0FLDS) = 50 
(I4,A15,A15,I4),GET 



Writing a Data Item 

The sample program uses a standard PRINTNUM to write to LINE/SPACES. 
PRINTNUM N01,F0RMAT=(5,G,I),LINE=18,PR0TECT=YES 

Reading a Data Item 

To do a read from LINE/SPACES, a prompt field is required. The null prompt text 
statement (NULPRMPT) is used. 

TERMCTRL SET,ATTR=HIGH 

READTEXT TEXTIN, NULPRMPT, LINE=23,SPACES=70 






Data Stream Considerations 

Applications that generate complex data streams for the 3151, 3161, 3163, and 3164 
terminals running in block mode (or 3101 emulation block mode) should provide 
their own pacing support. Repeated writing of large data streams containing 
multiple escape sequences may cause the terminal's internal buffer to be overrun. 
This results in truncation of the data stream. A sufficient delay should occur 
between terminal output operations which involve this type of data stream. 
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Example 



SAMPLE 
lOCBl 



PROGRAM START 



lOCB 



SCREEN=STATIC 



\\ 



* THIS PROGRAM USES A 3101 TERMINAL TO ILLUSTRATE* 

* EBCDIC ESC SEQUENCES AND DATA STREAMS VIA PRINTEXT* 



IE 



fl 



m 





DATA 


X'0202' 




ERASEFLD 


DATA 


X'27C9' 






DATA 


X'0303' 




SETMOD 


DATA 


X'27F3' 






DATA 


X'C500' 






DATA 


x'oior 




ATTRBUTE 


DATA 


X'OOOO' 






DATA 


X'O202' 




BACKTAB 


DATA 


X'27F2' 






DATA 


x'oior 




TAB 


DATA 


X'O50O' 




NULPRMPT 


TEXT 


LENGTH=0 




START 


EQU 


* 






ENQT 


lOCBl 






TERMCTRL 


SET,ATTR=LOW 






ERASE 


TYPE=ALL 






PRINTEXT 


ATTRBUTE, LINE=O,SPACES=0,PROTECT=YES 




TERMCTRL SET,ATTR=HI6H 






PRINTEXT 


ATTRBUTE, LINE=4,SPACES=29 






PRINTEXT 


ATTRBUTE, LINE=6,SPACES=29 






PRINTEXT 


ATTRBUTE, LINE=8,SPACES=29 






TERMCTRL 


SET,ATTR=LOW 






PRINTEXT 


ATTRBUTE , LINE=4 , SPACES=34 , PROTECT=YES 






PRINTEXT 


ATTRBUTE, LINE=6,SPACES=45,PR0TECT=YES 






PRINTEXT 


ATTRBUTE, LINE=8,SPACES=45,PR0TECT=YES 






PRINTEXT 


HEAD1,LINE=1,SPACES=20,PR0TECT=YES 






PRINTEXT 


'ENTER A NUMBER', LINE=4,SPACES=2, 
PROTECT=YES 


C 




PRINTEXT 


'THIS IS FIELD2',LINE=6,SPACES=9, 
PROTECT=YES 


C 




PRINTEXT 


'THIS IS FIELD3',LINE=8,SPACES=9, 
PROTECT=YES 


C 


NONDISP 


TERMCTRL 


SET,ATTR=BLANK 






PRINTEXT 


'ENTER ANOTHER NUMBER' ,LINE=12,SPACES=2, 
PROTECT=YES 


C 



r 
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Q Define a dummy TEXT statement with length of 2 and count of 2. 
Q Erase end of field sequence. 

01 Define a dummy TEXT statement with length of 3 and count of 3. 
Q Start field sequence. 

Q Set ATTR = HIGH, unprotected, with modified data tag on. 
Q Define a dummy TEXT statement with length of 1 and count of 1 . 
Q Null (to force attribute to write). 

Q Define a dummy TEXT statement with length of 2 and count of 2. 
Q Back tab to first character position of unprotected field. 
ffol Define a dummy TEXT statement with length of 1 and count of 1 . 
IQ Horizontal tab to next field. 
[Q Used on impUed wait instructions. 
IQ Start screen with protected field at 0,0. 
Ql Set intensity to high. 
m Set the start of unprotected field. 
3 Set the intensity to low. Now set the end of unprotected fields. 



Hi Create protected hterals as new fields. This could be done with ATTR = NO as 
screen is protected. 

EIQ Nondisplay this literal field at this time. 
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m 


TERMCTRL 


SET,ATTR=HIGH 


* 


NORMAL 


GETVALUE = #PROMPT# 


■k 


NULL 


PROMPT GETVALUE = # 


GETVAL 


GETVALUE 


FIELDING, NULPRMPT,LINE=4,SPACES=29 




DIVIDE 


FIELDING, 2, RESULT=DUMMY 




IF 


(SAMPLE, NE,0) 


IB BLINK 


TERMCTRL 


SET,ATTR=BLINK 




PRINTEXT 


'FIELDl MUST BE EVEN ' ,LINE=2,SPACES=5 
PROTECT=YES 


Q 


TERMCTRL 


SET,ATTR=HIGH 


Bl ERASEF 


PRINTEXT 


ERASEFLD,LINE=4,SPACES=29 




GOTO 


GETVAL 




ELSE 




Bl 


TERMCTRL 


SET, ATT R=B LANK 




PRINTEXT 


ATTRBUTE , LI NE=2 , SPACES=5 , PROTECT=YES 




TERMCTRL 

* 


SET,ATTR=HIGH RESTORE ATTRIBUTE 
* 


Bel SCATTER 


PUTEDIT 

ENDIF 
* 


F0RMAT1,TEXT0UT,(AS,TAB,BS),LINE=6, 
SPACES=2 


EI QUEST 


QUESTION 


'WANT TO SEE MORE ?' ,NO=ENDIT,LINE=10, 



EI LIGHT 
icTel CREATEU 

icCT 



SPACES=5 

* QUESTION AND INVALID RESPONSES CAN YIELD 

* #PROMPT#?#?#?#?#_ 

* NEED TO FIND ALL ATTRIBUTES '#' AND CLEAR 
RDCURSOR LINE, SPACES FIND CURSOR 

PRINTEXT LINE=LINE,SPACES=SPACES 

TERMCTRL DISPLAY 

DO UNTIL, (SPACES, EQ, 5), AND, (LINE, EQ, 10) 

TERMCTRL SET,ATTR=NO 

PRINTEXT BACKTAB 

RDCURSOR LINE, SPACES 

SUB SPACES, 1 

TERMCTRL SET,ATTR=BLANK 

PRINTEXT ATTRBUTE, LINE=LINE,SPACES=SPACES,PROTECT=YES 

ENDDO 

TERMCTRL SET,ATTR=LOW 

PRINTEXT ATTRBUTE, LINE=12,SPACES=2,PR0TECT=YES 

PRINTEXT 'ON A WAIT KEY NOW ,LINE=13,SPACES=9, 

PROTECT=YES 

TERMCTRL SET,ATTR=LOW 

PRINTEXT ATTRBUTE, LINE=12,SPACES=34,PR0TECT=YES 

TERMCTRL SET,ATTR=HIGH 

PRINTEXT ATTRBUTE, LINE=12,SPACES=29 

WAIT KEY 
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on Restore attribute. 

M J) EQ Create new protected blinking field. 

^3 Restore attribute. 

1^ Going to erase an individual field using erase. 

J^ Blank out blinking field by going nondisplay. 

Qj Do scatter write by inserting tab character. 

03 Going to do standard question. 

03 Force soft cursor address to be updated. 

03 Find unprotected field cursor is in. 

001 Adjust to attribute byte. 

^3 Prepare to blank it. 

1^ Light up nondisplay field4 prompt. 

03 Create new unprotected field with cursor in place. 

^3 Restore attribute. 
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K 1 


TERMCTRL 


LOCK 


Bi 


TERMCTRL 


SET,ATTR=NO 




PRINTEXT 


SETM0D,LINE=12,SPACES=29 




PRINTEXT 


SETM0D,LINE=4,SPACES=29 




TERMCTRL 


SET,ATTR=YES RESTORE 


READMOD 


READTEXT 


MTEXT,TYPE=MODDATA,MODE=LINE 


m 


IF 


{MTEXT,NE,MTEXT+4,4) 




TERMCTRL 


SET,ATTR=BLINK 




PRINTEXT 


'FLD4 MUST = FLDl ' ,LINE=13,SPACES=9, 
PROTECT=YES 


Q 


TERMCTRL 


SET,ATTR=HIGH 


kH ERASEF2 


ERASE 


5,TYPE=ALL,LINE=4,SPACES=29 




PRINTEXT 


LINE=6,SPACES=29 




TERMCTRL 


DISPLAY 


IS ERASEUNP 


ERASE 


TYPE=DATA 




TERMCTRL 


UNLOCK 




GOTO 


GETVAL 




ENDIF 






TERMCTRL 


UNLOCK 


GETALL 


GETEDIT 


F0RMAT2 , TEXTAMT , (NOl , ALPHl ,ALPH2 , N02) 




TERMCTRL 


SET,ATTR=BLINK 




PRINTEXT 


'YOU ENTERED: ' ,LINE=16,PR0TECT=YES 




TERMCTRL 


SET,ATTR=HIGH 




PRINTNUM 


N01,F0RMAT=(5,0,I),LINE=18,PR0TECT=YES 




PRINTEXT 


ALPHl , LINE=19 , PROTECT=YES 




PRINTEXT 


ALPH2 , LINE=20 , PROTECT=YES 




PRINTNUM 


NO2,FORMAT=(5,0,I),LINE=21,PROTECT=YES 




TERMCTRL 


DISPLAY 


ENDIT 


EQU 


* 




TERMCTRL 


SET,ATTR=LOW 




PRINTEXT 


'IF YOU WANT TO SEE IT AGAIN ENTER "AGAIN 
LINE=23,SPACES=5,PR0TECT=YES 




TERMCTRL 


SET,ATTR=HIGH 


m 


READTEXT 


TEXTIN, NULPRMPT,LINE=23,SPACES=70 




IF 


(TEXTIN, EQ.CAGAIN, 5) , GOTO, START 




PROGSTOP 


LOGMSG=NO 


FORMAT 1 


FORMAT 


(A15,A1,A15),PUT 


^ TEXTOUT 


TEXT 


LENGTH=31 


LINE 


DATA 


F'O' 


SPACES 


DATA 


F'O' 


FIELDING 


DATA 


F'O' 


HEADl 


TEXT 


•*** 3101 SAMPLE PROGRAM ***' 


gg MTEXT 


TEXT 


LENGTH=8 


DATABFR 


DATA 


C ' AAAAAAAAAAAAAAABBBBBBBBBBBBBBB ' 


AS 


EQU 


DATABFR 


BS 


EQU 


AS+15 


Eg TEXTAMT 


TEXT 


LENGTH=38 


F0RMAT2 


FORMAT 


(I4,A15,A15,I4),GET 


NOl 


DATA 


F'O" 


N02 


DATA 


F'O' 


ALPHl 


TEXT 


LENGTH=15 


ALPH2 


TEXT 


LENGTH=15 


C AGAIN 


DATA 


C AGAIN' 


TEXTIN 


TEXT 


' ',LENGTH=5 


DUMMY 


DATA 

ENDPROG 

END 


F'O' 



,Y"^. 
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Reading Data from and Writing to Screens 

Kfl Lock the keyboard. 

Bi To write MDT on attribute. 

IQ Pseudo testing. Read these two fields with TYPE = MODDATA. 

1^ Restore. 

Q Erase FLD 1. 

IQ Erase remaining unprotected fields. 

K?tl Finally a READTEXT to hne and space. 

KH Size of data stream. 

Bel ReadofModdataLGTH= DATA + (4*NOFLDS). 

d Getedit stream LGTH= DATA + (3*NOFLDS). 
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f^ Chapter 9. Designing Programs 

This chapter discusses designing EDL programs. 






All of the programs shown so far have had one thing in common: they are all short, 
self-contained groups of instructions that perform a simple function without 
interacting with any other program. 

This chapter: 

• Defines the terms program and task and describes how to create a program that 
consists of more than one task 

• Describes how to use the same group of instructions from more than one 
program 

• Shows how to use the same storage more than once for different parts of a 
program (overlays) 

• Shows how to improve performance by using storage as a buffer area. 



What Is a Task? 

A task is a unit of work that you form by combining instructions. In its simplest 
form, a task consists of a TASK statement, instructions, and an ENDTASK 
•>t^ statement. 



Each task runs independently, competing equally with other tasks for system 
resources. 

When you code a task, you assign a priority to the task. A priority is a number that 
determines the rank of the task. The supervisor uses priority to determine which 
task receives system resources. The highest priority is 1 and the lowest is 510. 

In the following example, TASKOl is the name of a task. STARTOI is the label on 
the first instruction to be executed, and 140 is the priority of the task. 

TASKGl TASK START01,14O 



ENDTASK 

The supervisor places each task in one of five states: 

State Description 

Inactive Task is detached or is not yet attached 

Waiting Task is waiting for the occurrence of an event or the availabihty of a 

resource 

Ready Task is ready but is not the highest priority task 

Active Task is attached and is the highest priority task on its level 

Executing Task is using the processor. 
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Only one task can be active on each of four machine hardware levels. (The 
supervisor executes on hardware level 1; application programs usually execute on 
hardware level 2 or 3.) 

The active task in each hardware level is the ready task that has the highest priority 
and is not waiting for an event or a resource. 



Initiating a Task 



You can initiate a task either by loading or attaching it. The system places the 
primary task in the ready state when you load the program. You can initiate a 
secondary task with the ATTACH statement if the task is not already active and you 
do either of the following: 

• You write a program that consists of a primary task and a secondary task. 

• You hnk edit a primary task with another task. (You must code an EXTRN 
statement in the primary task and an ENTRY statement in the secondary task.) 

You return a task to the inactive state when you execute either a DETACH 
instruction or ENDTASK instruction. The DETACH instruction suspends the task 
and allows it to be attached again. 

Only one copy of a task may be active at a time. A task in processor storage 
remains until you execute an ENDPROG statement in the associated primary task. 



What Is a Program? 



A program is a disk- or diskette-resident collection of one or more tasks that can be 
loaded into storage for execution. Although program and task are sometimes used 
synonymously (when a program contains a single task), the basic executable unit is 
the task; a program is the unit that the system loads into storage. 

You can divide a program into two or more tasks if, for example, you need to 
synchronize execution between the tasks. Another reason to divide a program into 
tasks is to have more than one task active at the same time. 

The name of a program is the name of the data set in which the program resides. A 
program can be brought into storage either by a terminal operator, a program, or a 
supervisor program such as the job stream processor. It can be loaded more than 
once, either in the same partition or in a different partition. 
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Creating a Single-Task Program 






Most applications consist of a single task in a single program. The program 
contains no execution overlay. The task competes for system resources with other 
tasks currently in the system. 

The following example shows the structure of a single-task program: 
BEGIN PROGRAM START 



PROGSTOP 

ENDPROG 

END 

In this example, BEGIN is the name of the task, and START is the label of the first 
instruction to be executed. 

Note that even though the TASK statement is not required in a simple program, the 
program still consists of a single task. 

Figure 9-1 on page 9-4 is an example of a single-task program structure. 
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Operator request loads 
CUSTOMER FILE UPDATE 
program 



UPDATE 

1. GET CUSTOMER NAME FROM TERMINAL (OPERATOR INPUT) 

2. SEARCH CUSTOMER FILE FOR NAME 

3. READ CUSTOMER RECORD 

4. DISPLAY CUSTOMER RECORD ON TERMINAL 

5. ACCEPT UPDATE FROM TERMINAL (OPERATOR INPUT) 

6. WRITE UPDATED RECORD TO CUSTOMER FILE 

7. GO BACK TO STEP 1 IF MORE RECORDS TO UPDATE 

8. ELSE, END UPDATE PROGRAM 
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Figure 9-1. Single-Task Application Example 
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Creating a Multitask Program 



A multitask program contains more than one task. For example: 
BEGIN PROGRAM START 



ATTACH CALC 



CALC 



PROGSTOP 

TASK 

instructions 

ENDTASK 

ENDPROG 

END 



g^^ 

V^' 



Note that the PROGRAM and PROGSTOP statements define a task called the 
primary task. The TASK and ENDTASK statements define a secondary task, loaded 
by the ATTACH instruction. 

Figure 9-2 illustrates multitasking in a single program. When you load the program, 
the system loads PROGA, called the primary task. The other tasks shown in 
PROGA start when an active task issues a command (such as an ATTACH 
instruction) that tells the tasks to begin. 



PROGA 



TASKX 



TASKY 



TASKZ 



Program made up of multiple tasks 

• Concurrent (asynchronous) execution 
of tasks within a program 

• Tasks compete for system resources 
with all other tasks currently in system 
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Figure 9-2. Multitask Program Structure 

Once in execution, all tasks within a program compete with one another and with all 
other tasks active in the system. The supervisor considers each task as a discrete 
unit of work and assigns processor time based on task priority, regardless of whether 
a task is the primary task of a program. All tasks compete for resources based on 
assigned priorities. 

If a primary task ends before the secondary task, the secondary task runs to 
completion. 
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Synchronizing Tasks 

You can synchronize tasks with the WAIT and POST instructions or with the 
DETACH and ATTACH instructions. If you use the WAIT and POST instructions, 
the waiting task must contain an event control block (ECB) that can be posted by 
the POST instruction. Execution then continues in the waiting task at the first 
instruction after the WAIT instruction. A task can also wait for the operator to 
press a Program Function (PF) key, for a time interval to occur, or for a program to 
finish execution. 

While waiting to be posted, the task enters a waiting state. The task also enters a 
waiting state if it is waiting for a read or write operation to occur or if it has 
executed a DETACH instruction. 

You can use the DETACH and ATTACH instruction to synchronize tasks the same 
way you use the WAIT and POST instruction, with the following differences: 

• The attached task becomes enqueued to the currently active terminal for the task 
that issued the ATTACH instruction. 

• The system provides the ECB. 

• You cannot use the ATTACH and DETACH instructions from within 
subroutines. 



Defining and Calling Subroutines 



In a program, certain functions may need to be repeated at different points in a 

program. For example, you do not need to code the same sequence of instructions 

each time your program needs to perform a given arithmetic function. You can \^ 

code the instructions once and define them as a subroutine. You can than enter and 

execute that subroutine from as many points in your program as needed. You can 

also use the subroutine in another program by including it at link-edit time. 

The following instructions provide the means for defining and calhng subroutines: 

CALL Transfers control to a subroutine 

RETURN Returns control from the subroutine to the calling program 

SUBROUT Defines the entry point and parameters of a subroutine 

EXTRN Defines an external reference 

ENTRY Defines a program entry point. 



9-6 SC34-0943 



Designing Programs 



Defining a Subroutine 

Use SUBROUT to define the entry point of a subroutine. You can specify up to 
five parameters as arguments in the subroutine. The subroutine must include a 
RETURN instruction to provide linkage back to the caUing task. You can have 
nested subroutines, and a maximum of 99 subroutines are permitted per program. If 
you assemble your subroutine as an object module that can be link edited, you must 
code an ENTRY statement for the subroutine entry point name. 

You can call a subroutine from more than one task. When called, the subroutine 
executes as part of the calling task. Because subroutines are not reentrant, you 
should ensure serial use of the subroutine with the ENQ and DEQ instructions. 

Note: Do not code a TASK statement within a subroutine. 

The syntax of the SUBROUT instruction is as follows: 
label SUBROUT name, pari,..., par5 

Required: name 
Defaults: none 
Indexable: none 

Code the name operand with the symbolic name of the subroutine to be referred to 
by other instructions. The label field is optional. Do not confuse the label field with 
the subroutine name you specify in the name operand. 

Passing Parameters in a Subroutine (Example) 

Pari through par5 are the parameter names to be passed to the subroutine when it is 
entered. These names must be unique to the whole program. All parameters defined 
./ outside the subroutine are known within the subroutine. Thus, you need to define 

only parameters that may vary with each call to a subroutine. 

For instance, assume two calls are made to the same subroutine. The first call 
passes parameters A and C and the second CALL passes parameters B and C. 
Because C is common to both, you need not define it in the SUBROUT instruction. 

In the following example, a program calls subroutine CHKBUFF, passing two 
parameters. The first (BUFFLEN) is a variable containing the maximum allowable 
buffer count. The second (BUFFEND) is the address of the instruction to be 
executed if the buffer is full. 

SUBROUT CHKBUFF, BUFFLEN, BUFFEND 



SUBTRACT BUFFLEN,! 

IF (BUFFLEN, GE, MAX) 

GOTO (BUFFEND) 
ENDIF 

ADD BUFFLEN, 1 

RETURN 






MAX DATA F'256' 
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Calling a Subroutine 

Use the CALL instruction to execute your subroutine. 

If the called subroutine is a separate object module to be Hnk edited with your 
program, then you must code an EXTRN statement for the subroutine name in the 
calhng program. 

The syntax of the CALL instruction is as follows: 
label CALL name,parl,. . . ,par5,Pl=,. . .,P6= 

Required: name 
Defaults: none 
Indexable: none 

The name operand is the name of the subroutine to be executed. 

Pari through par5 are the parameters associated with the subroutine. You can pass 
up to five single-precision integers, labels of single-precision integers, or null 
parameters to the subroutine. The actual constant or the value at the named 
location moves to the corresponding subroutine parameter. 

If you enclose the parameter name in parentheses, the address of the variable passes 
to the subroutine. The address can be the label of the first word of any type of data 
item or data array. Within the subroutine, you must move the passed address of the 
data item into index registers #1 or #2 to reference the data item. If the parameter 
name enclosed in parentheses is a symbol defined by an EQU instruction, the system 
passes the value of the symbol. 

If the parameter to be passed is the value of a symbol defined by an EQU 
instruction, it can also be preceded by a plus ( + ) sign. This causes the value of the 
EQU to be passed to the subroutine. If not preceded by a + , the EQU is assumed 
to represent an address and the data at that address is passed as the parameter. 

Subroutine Call Examples 

The following example passes the value 5 to the subroutine PROG: 

CALL PROG, 5 

The following example passes the value 5 and the null parameter to the subroutine 
CALC: 

CALL CALC, 5, 

The following example passes the contents of PARMl, the address of PARM2, and 
the value of the EQU symbol FIVE: 

CALL SUBROUT, PARMl, (PARM2),+FIVE 
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Calling a Subroutine Passing Integer Parameters (Example) 

The following example shows a program that passes integers to a subroutine: 



SUBEXAMP 
START 



PROGRAM 
CALL 



START 
CALC,5G,SUM1 



C2 


CALL 

• 


CALC,SUM1,SUM2 




• 
PROGSTOP 




INTEGERA 


DATA 


F'lO' 


INTEGERS 


DATA 


F'15' 


SUMl 


DATA 


F'O' 


SUM2 


DATA 


F'O" 


SUBl 


SUBROUT 


CALC,XVAL,YVAL 


Al 


ADD 

RETURN 
ENDPROG 
END 


INTEGERA, XVAL,RESULT=YVAL 



In the first CALL, the first parameter (the integer value 50) corresponds to the first 
parameter defined in the subroutine (XV AL). Program location SUMl corresponds 
to the second parameter (YVAL). When the ADD instruction executes, the system 
substitutes 50 for XV AL and location SUMl for YVAL. After the ADD 
instruction, SUMl equals 60, the sum of INTEGERA and 50. 

The second call causes 70, the sum of SUMl and INTEGERA, to be put in location 
SUM2. Because INTEGERA does not change, you do not need to pass it as a 
parameter. 



Reusing Storage using Overlays 



You can reuse a single storage area allocated to a program by using overlays. EDL 
provides two kinds of overlays: overlay segments and overlay programs. 

An overlay segment is a self-contained portion of a program that is called and 
executed as a synchronous task. The program that calls the overlay segment need 
not be in storage while the overlay segment is executing. Overlay segments perform 
a specific function and generally execute only once. 

An overlay program is a self-contained portion of a program that is loaded and 
executed as an asynchronous task. Overlay programs require a main control program 
that controls the execution of up to nine overlay programs. 
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Using Overlay Segments 



Figure 9-3 shows the structure of an appHcation program that is spUt into a root 
segment and three overlay segments. 



APPLICATION PROGRAM 





Root segment 






Overlay area manager 
























Overlay 
segment 1 




Overlay 
segment 2 




Overlay 
segment 3 
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Figure 9-3. Application Overlay Segments 

When you load the main program, the loader reserves enough space for the root 
segment, the overlay area manager, the overlay control table, and the largest overlay 
segment as shown in Figure 9-4. 

SERIES/1 STORAGE 



Root (resident) segment 



$OVLMGR 
Overlay manager 



$OVLCT 

Overlay control table 



Overlay area 

(large enough to contain 

segment 2) 



Available storage 
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Figure 9-4. Overlay Segments in Series/1 Storage 
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The following example shows a root segment and three overlay segments: 

BEGIN PROGRAM START 

EXTRN CALC, UPDATE, WRITE 



CALL CALC 



CALL UPDATE 



CALL WRITE 



PROGSTOP 
ENDPROG 

END 

******************************************************************* 

* OVERLAY SEGMENT 1 * 

****************************************************************** 

SUBROUT CALC 
ENTRY CALC 
instructions 
RETURN 

END 

****************************************************************** 

* OVERLAY SEGMENT 2 * 

****************************************************************** 

SUBROUT UPDATE 
ENTRY UPDATE 

instructions 
RETURN 

END 

****************************************************************** 

* OVERLAY SEGMENT 3 

****************************************************************** 

SUBROUT WRITE 
ENTRY WRITE 
instructions 
RETURN 
END 

Each of the overlay segments is a subroutine that you can compile separately. 
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Creating an Overlay Structure 

To create an overlay structure, use the linkage editor $EDXLINK. The linkage 
editor allows you to combine the overlay segments you link edited separately into a 
program segment overlay structure. SEDXLINK automatically includes an overlay 
manager with the root segment, along with an overlay area equal to the largest 
overlay segment. A CALL (or transfer of control) to a module within an overlay 
segment triggers the overlay area manager to load the overlay segment into the 
overlay area and transfer control to it. Overlay segments execute as synchronous 
tasks. An overlay segment cannot call another overlay segment. 



Overlay segments are specified in the OVERLAY statement of SEDXLINK which is 
discussed in detail in Chapter 5, "Preparing an Object Module for Execution." 

Overlay Programs 

An overlay program is a program in which certain control sections can use the same 
storage location at different times during execution. Overlay programs execute 
concurrently as asynchronous tasks with other programs and are specified in the 
PROGRAM statement in the main program. 

With overlay programs, the main program loads the overlay programs. The loader 
allocates the overlay area for overlay programs at main program load time. The 
overlay area is equal to the largest overlay program hsted in the main program 
header. 

In Figure 9-5, the application is spht into separate programs. PHASE 1, the primary 
program, loads the overlay programs (PHASE2, PHASE3, and PHASE4) as 
requested. 

PHASE1 

application 

program 



PHASE1 



PHASE2 



PHASES 



PHASE4 
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Figure 9-5. EDL Overlay Programs 



o 
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When PHASE 1 is loaded, the loader recognizes that overlay programs are 
referenced. The loader looks at each overlay program and reserves enough storage 
to hold PHASE 1 plus the largest overlay program (PHASE3) as shown in 
Figure 9-6. 






Series/1 storage 



Space for PHASE1 
plus overlay area 
reserved when 
PHASE1 is loaded 



Supervisor 



PHASE1 



(Overlay area) 



(Available 
storage) 



Overlay area large 
enough for PHASES, 
the largest overlay 
program 
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Figure 9-6. EDL Overlay Programs in Series/ 1 Storage 

As each overlay program completes execution, PHASE 1 loads the next overlay 
program, until all required programs have run. When PHASE 1 terminates, the 
system releases the storage reserved for PHASE! and its overlay programs. Refer to 
the Language Reference for information on coding the PROGRAM statement for 
overlays. 



Using Large Amounts of Storage (Unmapped Storage) 

Unmapped storage allows you to write a program that uses large amounts of 
storage. Unmapped storage allows you to store large amounts of data and retrieve 
data faster than you could retrieve it from disk or diskette. This section describes 
setting up, obtaining, accessing, and releasing unmapped storage. 

What Is Unmapped Storage? 

Unmapped storage is physical storage that has not been reserved by the SYSPARTS 
statement during system initiahzation. 
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Setting up Unmapped Storage 

Use the STORBLK statement to define the size and number of the unmapped 
storage areas a program will use. The TWOKBLK operand defines the size of each 
unmapped storage area. For example, if you need unmapped storage areas to 
accom.m.odate 6000 bytes of data, code TWOKBLK = 3 (6K = 6144 bytes). The 
maximum size of an unmapped storage area is 63,488 bytes (TWOKBLK = 31). 

The MAX operand defines the number of unmapped storage areas. For example, if 
you need ten unmapped storage areas, code MAX= 10. 

In the following example, HOLD defines 16 (MAX= 16) 2K-byte areas of unmapped 
storage. 

HOLD STORBLK TW0KBLK=1,MAX=16 

The STORBLK statement also sets up a mapped storage area the same size as the 
unmapped storage area. 

Obtaining Unmapped Storage 

Use the GETSTG instruction to obtain the mapped and unmapped storage areas 
you defined in the STORBLK statement. For example: 

GETSTG HOLD,TYPE=ALL 

This instruction obtains the mapped and unmapped storage that you defined in the 
STORBLK statement with the label HOLD. The size of the area depends on the 
TWOKBLK operand of the STORBLK statement. The operand TYPE = ALL tells 
the system to obtain the unmapped and mapped storage areas. The number of 
unmapped storage areas the system obtains depends on the MAX parameter of the 
STORBLK statement. 

If you want to obtain only one unmapped storage area, code the GETSTG 
instruction as follows: 

GETSTG HOLD,TYPE=NEXT 

The instruction causes the system to obtain an unmapped storage area that you 
defined in the STORBLK statement with the label HOLD. The size of the area 
depends on the TWOKBLK operand of the STORBLK statement. The system 
obtains one unmapped storage area. For example, if you specified MAX = 24 on the 
STORBLK statement and the system had already obtained fifteen unmapped storage 
areas, the system would obtain the sixteenth one. 



o 
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Using an Unmapped Storage Area 

You can use an unmapped storage area just like you would use any other storage 
area. For example, you can move data into the area or perform calculations on data 
within the area. 

The SWAP instruction allows you to use an unmapped storage area. For example: 
SWAP HOLD,USANO 

The instruction allows you to access the unmapped storage area defined by the 
STORBLK statement at label HOLD. The operand USANO refers to the label of a 
DATA statement that defines the number of the unmapped storage area you want to 
access. For example, if USANO contains "5," the SWAP instruction allows the 
program to access the fifth unmapped storage area. 

You can also code the number of the unmapped storage area you want to use: 
SWAP HOLD, 10 

This instruction allows you to use the tenth unmapped storage area defined by the 
STORBLK statement at label HOLD. Until you execute another SWAP instruction, 
you can use only the tenth unmapped storage area. 

Notes: 

1. You can use only one unmapped storage area at a time. 

2. While you are using an unmapped storage area, you cannot use the mapped 
storage area. 

Releasing Unmapped Storage 

Use the FREESTG instruction to release any unmapped storage area that you 
obtained with the GETSTG instruction. For example: 

FREESTG HOLD,TYPE=ALL 

This instruction releases the unmapped storage areas defined by the STORBLK 
statement at label HOLD. The operand TYPE = ALL causes the instruction to 
release all of the storage areas. For example, if the STORBLK statement specifies 
MAX = 1 6, this instruction causes all sixteen unmapped storage areas and the 
mapped storage area to be released. 



^^k 
^t^ 
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Example 



The following example uses ten unmapped storage areas to create a table of actuarial 
data. The table for each of the ten countries consists of four-digit mortahty rates. 
The program accumulates 100 rates for both men and women. The unmapped 
storage the program uses is determined by the country number. 






The input records have the following format: 



Country 


number 


2 bytes 


Age 




2 bytes 


Death rate 


4 bytes 


Sex code 




1 byte 


The program: 






INSURE 


PROGRAM 


ST , DS= ( ( ACTTAB , EDX40) , (ACTOUT , EDX40) ) 




COPY 


STOREQU 


ST 


GETSTG 


HOLD,TYPE=ALL 




MOVE 


USANO,! 


MOVE 


#1,H0LD+$ST0RMAP 




DO 


10 


SWAP 


HOLD, USANO, ERROR=SWAPERR 




MOVE 


(+MENTBL,#1),C' ',(800, BYTE) 




ADD 
ENDDO 


USANO,! 


1 READ 


READ 


DS1,M0RTAL,1,END=ST0P 


J 


CONVTD 


CNTRYC,CNTRY,PREC=S,F0RMAT=(2,0,I) 


1 


MOVE 


#1,H0LD+$ST0RMAP 


? 


SWAP 


HOLD , CNTRYC , ERROR=SWAPERR 




CONVTD 


AGEC,AGE,PREC=S,F0RMAT=(2,0,I) 


1 


MOVE 
MULT 


#2,AGEC 
#2,4 


I 


ADD 


#1,#2 




IF 


(SEX, EQ, ONE, BYTE) 




MOVE 
ELSE 


(+MENTBL,#1) ,RATE, (4, BYTES) 




MOVE 


(+WMNTBL,#1), RATE, (4, BYTES) 




ENDIF 






GOTO 


READ 


Q STOP 


MOVE 


USANO,! 


5 1 


MOVE 


#!,HOLD+$STORMAP 


! 1 


DO 
SWAP 


!0 
HOLD , USANO , ERROR=SWAPERR 


! 


MOVE 


OUTAREA, (+MENTBL,#!) , (400, BYTES) 


» 

{ 1 


WRITE 


DS2,0UTAREA,2,0,END=E0FILE,ERR0R=WRERR 


MOVE 


OUTAREA, (+WMNTBL,#1) , (400, BYTES) 


i i 


WRITE 


DS2, OUTAREA, 2, 0,END=EOFILE,ERROR=WRERR 


! 1 


ADD 
ENDDO 


USANO,! 




GOTO 


END 
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Q Copy the storage control block equates into the program. 

Q Obtain the mapped and unmapped storage (one 2K-byte mapped storage area 
and ten 2K-byte unmapped storage areas) specified in the STORBLK statement with 
the label HOLD. 

Q Initiahze USANO to 1. 

Q Move the address of the mapped storage area to register 1 . 

01 Begin a loop to initialize all ten unmapped storage areas to blanks. 

Q Access an unmapped storage area. 

Q Move blanks to the first 800 positions of the unmapped storage area. 

Q Add 1 to USANO so that the SWAP instruction accesses the next unmapped 
storage area. 

Q Read an input record from data set ACTTAB on volume EDX40 into the buffer 
with the label MORTAL. 

BBI Convert the country number in the input record to binary and put the result in 
CNTRYC. 

m Move the address of the mapped storage area into register 1 . 



Use the country number (in CNTRYC) to access the appropriate unmapped 
storage area. 

IH Convert the age in the input record to binary and put the result in AGEC. 

Q] Move the age (in AGEC) into register 2. 

[Q Multiply the age by 4 to arrive at the proper offset into the table. 

IH Add the offset to the address of the mapped storage area. 

Test the sex code for 1 (1 = men). 



IH Move the mortahty rate into the appropriate slot in the MENTBL (the men's 
mortahty rate table). 



J Initiahze USANO to 1. 
KH Move the address of the mapped storage area to register 1 . 
fH Begin a loop to write records from the unmapped storage areas. 
[^ Access an unmapped storage area. 
Bel Move a man's mortality rate table to OUTAREA. 
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EQ Write an output record to data set ACTOUT on volume EDX40 from the 
buffer with the label OUTAREA. 



Move a woman's mortahty rate table to OUTAREA. 



X..J^ 



03 Write an output record to data set ACTOUT on volume EDX40 from the 
buffer with the label OUTAREA. 



Add 1 to USANO so that the SWAP instruction accesses the next 



EOFILE 


EQU 


* 




PRINTEXT 


'0** ACTUARIAL FILE HAS EXCEEDED DISK : 




GOTO 


END 


SWAPERR 


EQU 


* 




MOVE 


TASKRC, INSURE 




IF 


(TASKRC, EQ,1) 




PRINTEXT '@** INVALID UNMAPPED STORAGE NUMBER 




ENDIF 






IF 


(TASKRC, EQ, 2) 




PRINTEXT '&** SWAP AREA NOT INITIALIZED' 




ENDIF 






IF 


(TASKRC, EQ, 100) 




PRINTEXT '@** NO UNMAPPED STORAGE SUPPORT' 




ENDIF 






GOTO 


END 


WRERR 


EQU 


* 




PRINTEXT 


'@** DISK WRITE ERROR ON ACTUARIAL DAL 




GOTO 


END 


END 


EQU 
PROGSTOP 


* 


ONE 


DATA 


F'l' 


USANO 


DATA 


F'O' 


TASKRC 


DATA 


F'O' 


AGEC 


DATA 


F'O' 


CNTRYC 


DATA 


F'O' 


OUTAREA 


BUFFER 


512, BYTES 


^ HOLD 


STORBLK 


TW0KBLK=1,MAX=10 


MENTBL 


EQU 





WMNTBL 


EQU 


MENTBL+300 


MORTAL 


BUFFER 


256, BYTES 


CNTRY 


EQU 


MORTAL 


AGE 


EQU 


MORTAL+2 


RATE 


EQU 


MORTAL+4 


SEX 


EQU 

ENDPROG 

END 


MORTAL+8 



c 



y 



^3 Set up a 2K-byte mapped storage area and ten 2K-byte unmapped storage 



areas. 
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1^ Chapter 10. Performing Data Management from a Program 

This section describes ways to accomplish data management from a program. 
Topics discussed are: 

• Allocating, deleting, opening, and renaming a data set 

• Opening a data set 

• Setting logical end of file 

• Finding the device type. 

To perform other data management functions from an apphcation program such as 
allocating, deleting, and renaming volumes, see Chapter 13, "Communicating with 
Other Programs (Virtual Terminals)." 

Allocating, Deleting, Opening, and Renaming a Data Set 

The $DISKUT3 program enables you to perform the following data management 
operations from a program: 

Allocate a data set 

Allocate a data set with extents 

Open a dat^ set 

Delete a data set 

Release unused space in a data set 

Rename a data set 

Set the end-of-data indicator in a data set. 

$DISKUT3 allows you to open and set the end-of-data indicator on disk, diskette, 
or tape data sets. You can perform the other operations (allocating, deleting, 
releasing unused space, and renaming) on disk or diskette data sets only. 

For more information on $DISKUT3, including a hst of return codes, refer to the 
Language Reference. 
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When to Use $DISKUT3 

You might use $DISKUT3 for any of the following reasons: 

• Your program requires more than nine data sets. 

• You do not know, at the time you load a program, whether or not the program 
will need a data set. 

• You need to perform several data management functions in one program. 

• You want the processor storage that $DISKUT3 requires to be available when 
$DISKUT3 finishes executing. 

To use $DISKUT3, you should be aware of the following factors: 

• $DISKUT3 requires about 6.25K bytes of processor storage. 

• If you need only to open a data set, $DISKUT3 will be slower than DSOPEN. 

• You need to perform error recovery if the system cannot load $DISKUT3. 






Allocating a Data Set 

The following example shows how to allocate a data set from an application 
program. An explanation of the numbered items follows the program. 

TASK PROGRAM GO 
GO EQU * 



B 



LOAD $DISKUT3 , LISTPTRl , EVENT=DSK3EVNT 
WAIT DSK3EVNT 








PROGSTOP 


DSK3EVNT 


ECB 





LISTPTRl 


DC 


A(LISTl) 


LISTl 


DC 


A(REQUESTl) 




DC 


F'O' 


REQUESTl 


DC 


F'2' 




DC 


A(DSX) 




DC 


D'50' 




DC 


FT 




DSCB 


DS#=DSX,DSNAME=DATA4 




COPY 


DSCBEQU 




ENDPROG 




END 
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Q Load $DISKUT3 to allocate data set DATA4. Specify the address (LISTPTRl) 
of the list of requests (in this case, a single request). Identify the event 
(EVENT = DSK3EVNT) to be posted when $DISKUT3 completes. 

B Wait for the system to indicate the end of $DISKUT3 by posting DSK3EVNT. 

Q Set the initial state of the event control block to zero. 

Q Point to the list of requests at LISTl. 

01 Point to the specific allocate request. 

Q Indicate the end of the list of requests. 

Q Request an allocate (2). 

01 Point to the DSCB for the data set to be allocated. (The allocate function 
requires that the data set being allocated be defined by a DSCB.) 

01 Indicate that 50 records are to be allocated. 

Ifol Indicate that the data set type is data. 

Define a DSCB for the data set to be allocated. 

Copy the DSCB equates into the program. 



If you attempt to allocate a data set that already exists, $DISKUT3 considers the 
operation successful if the type and size of the data set that already exists matches 
the type and size of the data set that you are allocating. 
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Allocating a Data Set with Extents 

The following example shows how to allocate a data set with extents from an 
appUcation program. An explanation of the numbered items follows the program. 






I 



TASK 


PROGRAM 


GO 


GO 


EQU 

• 




* 




• 
LOAD 


$DISKUT3 , LISTPTRl , EVENT=DSK3EVNT 




WAIT 

• 


DSK3EVNT 


DSK3EVNT 


• 
ECB 





LISTPTRl 


DC 


A(LISTl) 


LISTl 


DC 


A(REQUESTl) 




DC 


F'O' 


REQUESTl 


DC 


F'8' 




DC 


A{DSX) 




DC 


D'lOOO' 




DC 


FT 




DC 


4F'0' 




DC 


F'100' 




DSCB 


DS#=DSX,DSNAME=DATA45 




COPY 


DSCBEQU 




ENDPROG 






END 
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B Load $DISKUT3 to allocate data set DATA45. Specify the address 
(LISTPTRl) of the list of requests (in this case, a single request). Identify the event 
(EVENT = DSK3EVNT) to be posted when $DISKUT3 completes. 

B Wait for the system to indicate the end of $DISKUT3 by posting DSK3EVNT. 

B Set the initial state of the event control block to zero. 

B Point to the list of requests at LISTl. 

B Point to the specific allocate request. 

B Indicate the end of the list of requests. 

B Request an allocate with data set extents (8). 

B Point to the DSCB for the data set to be allocated. (The allocate function 
requires that the data set being allocated be defined by a DSCB.) 

B Indicate that the size of the primary data set is 1000 records. 



Q Indicate that the data set type is data (You can only allocate data-type data 
sets with this request.) 

Q] Allocate four words of zeroes. These fields are reserved. 

IB Indicate that the size of each extent is to be 100 records. 

IB Define a DSCB for the data set to be allocated. 

IB Copy the DSCB equates into the program. 

If you attempt to allocate a data set that already exists, $DISKUT3 considers the 
operation successful if the type and size of the data set that already exists matches 
the type and size of the data set that you are allocating. 
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Opening a Data Set 

If you have defined a data set with a DSCB, you need to open the data set from 
your apphcation program. 

The following example shows hov,' to open a data set from an apphcation program. 
An explanation of the numbered items foUows the program. 



B 



TASK 


PROGRAM 


GO 


GO 


EQU 

• 



* 




• 
LOAD 


$DISKUT3,LISTPTR1,EVENT=DSK3EVNT 




WAIT 


DSK3EVNT 



DSK3EVNT ECB 





LISTPTRl DC 


A(LISTl) 


LISTl DC 


A(REQUESTl) 


DC 


F'O' 


REQUESTl DC 


FT 


DC 


A(DSY) 


DC 


D'O" 


DC 


F'-l" 


DSCB 


DS#=DSY,DSNAME=DATA4 


COPY 


DSCBEQU 


ENDPROG 


END 





D Load $DISKUT3 to open data set DATA4. Specify the address (LISTPTRl) of 
the hst of requests (in this case, a single request). Identify the event 
(EVENT = DSK3EVNT) to be posted when $DISKUT3 completes. 

B Wait for the system to indicate the end of $DISKUT3 by posting DSK3EVNT. 

Q Set the initial state of the event control block to zero. 

Q Point to the hst of requests at LISTl. 

Qj Point to the specific open request. 

Q Indicate the end of the hst of requests. 

Q Request an open (1). 

Q Point to the DSCB for the data set to be opened. 

Q This doubleword is not used for an open request. 

EQ Tell $DISKUT3 to return the type of the data set being opened (0 for 
undefined, 1 for data, 3 for program). 



^^uiijlf' 
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m Define a DSCB for the data set to be opened. 
Copy the DSCB equates into the program. 



Deleting a Data Set 

The following example shows how to delete a data set (with or without extents) from 
an appUcation program. An explanation of the numbered items follows the 
program. 

TASK PROGRAM GO,DS=( (MASTER, EDXO02) , (UPDATE, EDXO03)) 
GO EQU * 






E 





LOAD 


$DISKUT3, LISTPTRl, EVENT=DSK3EVNT 




WAIT 

• 


DSK3EVNT 


DSK3EVNT 


• 
ECB 





LISTPTRl 


DC 


A(LISTl) 


LISTl 


DC 


A(REQUESTl) 




DC 


F'O' 


REQUESTl 


DC 


F'4' 




DC 


A(DS2) 




DC 


D'O' 




DC 


F'-r 




COPY 


DSCBEQU 




ENDPROG 






END 








Q Load $DISKUT3 to delete data set UPDATE on volume EDX003. Specify the 
address (LISTPTRl) of the list of requests (in this case, a single request). Identify 
the event (EVENT = DSK3EVNT) to be posted when $DISKUT3 completes. 

Q Wait for the system to indicate the end of $DISKUT3 by posting DSK3EVNT. 

Q Set the initial state of the event control block to zero. 

Q Point to the hst of requests at LISTl. 

Q Point to the specific delete request. 

Q Indicate the end of the hst of requests. 

Q Request a delete (4). 

Q Point to the DSCB for the data set to be deleted (UPDATE on volume 
(EDX003). 

Q This doubleword is not used for a delete request. 
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Q] Tell $DISKUT3 to return the type of the data set being deleted (0 for 
undefined, 1 for data, 3 for program). 

01 Copy the DSCB equates into the program. 

If you try to delete a data set that does not exist, $DISKUT3 considers the 
operation to be successful. 

Releasing Unused Space in a Data Set 

The following example shows how to release unused space in a data set from an 
appHcation program. An explanation of the numbered items follows the program. 



B 



TASK 


PROGRAM 


GO 


GO 


EQU 

• 



* 




• 
LOAD 


$DISKUT3, LISTPTRl, EVENT=DSK3EVNT 




WAIT 

• 



DSK3EVNT 


DSK3EVNT 


• 
ECB 





LISTPTRl 


DC 


A(LISTl) 


LISTl 


DC 


A{REQUEST1) 




DC 


F'O" 


REQUESTl 


DC 


F'5' 




DC 


A(DSX) 




DC 


D'lOO' 




DC 


F'-r 




DSCB 


DS#=DSX,DSNAME=TRANS 




COPY 


DSCBEQU 




ENDPROG 






END 





Q Load $DISKUT3 to release space on data set TRANS. Specify the address 
(LISTPTRl) of the list of requests (in this case, a single request). Identify the event 
(EVENT = DSK3EVNT) to be posted when $DISKUT3 completes. 

B Wait for the system to indicate the end of $DISKUT3 by posting DSK3EVNT. 

Q Set the initial state of the event control block to zero. 

Q Point to the hst of requests at LISTl. 

01 Point to the specific release request. 

Q Indicate the end of the list of requests. 

Q Request a release (5). 

01 Point to the DSCB for the data set on which space to be released (TRANS). 



c 
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Q Indicate the number of records you want the data set to contain. (This number 
must be greater than zero and less than the current number of records.) 

Ql Tell $DISKUT3 to return the type of the data set on which space is being 
released (0 for undefined, 1 for data, 3 for program). 



Define a DSCB for the data set on which to release unused space. 
Copy the DSCB equates into the program. 



Renaming a Data Set 



The following example shows how to rename a data set from an application 
program. An explanation of the numbered items follows the program. 

TASK PROGRAM GO, DS=( (MASTER, EDX003)) 

GO EQU * 



I 



LOAD $DISKUT3 , LISTPTRl , EVENT=DSK3EVNT 
WAIT DSK3EVNT 






DSK3EVNT ECB 





LISTPTRl DC 


A(LISTl) 


LISTl DC 


A(REQUESTl) 


DC 


F'O' 


REQUESTl DC 


F'3' 


DC 


A(DSl) 


DC 


F'O' 


DC 


A(NEWNAME) 


DC 


F'-l' 


COPY 


DSCBEQU 


NEWNAME DC 


CLS'NEWMAST 


ENDPROG 




END 





m .:iti 



Q Load $DISKUT3 to rename data set MASTER. Specify the address 
(LISTPTRl) of the list of requests (in this case, a single request). Identify the event 
(EVENT = DSK3EVNT) to be posted when $DISKUT3 completes. 

B Wait for the system to indicate the end of $DISKUT3 by posting DSK3EVNT. 

Q Set the initial state of the event control block to zero. 

Q Point to the list of requests at LISTl. 

Q Point to the specific rename request. 
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Q Indicate the end of the Hst of requests. 

Q Request a rename (3). 

Q Point to the DSCB for the data set to be renamed (MASTER on vol 
EDX003). 

Q This word is not used for a rename request. 

03 Point to the new data set name. 

m Tell $DISKUT3 to return the type of the data set being renamed (0 for 
undefined, 1 for data, 3 for program). 

IQ Copy the DSCB equates into the program. 

[Q Define the new name for the data set. 

Setting End-of-Data on a Data Set 

If you define a data set with a DSCB, you need to set the end-of-data indicator from 
your application program. 

The following example shows how to set the end-of-data indicator on a data set 
from an apphcation program. An explanation of the numbered items follows the 
program. 



TASK PROGRAM GO, DS=( (MASTER, EDX0O3) 
60 EQU * 



E 



LOAD $DISKUT3,LISTPTR1,EVENT=DSK3EVNT 
WAIT DSK3EVNT 



1 



DSK3EVNT ECB 





LISTPTRl DC 


A(LISTl) 


LISTl DC 


A(REQUESTl) 


DC 


F'O" 


REQUESTl DC 


F'6' 


DC 


A(DSl) 


DC 


D'O' 


DC 


F'-r 


COPY 


DSCBEQU 


ENDPROG 




END 
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Q Load $DISKUT3 to set the end-of-data indicator on data set MASTER. 
Specify the address (LISTPTRl) of the hst of requests (in this case, a single request). 
Identify the event (EVENT = DSK3EVNT) to be posted when $DISKUT3 
completes. 

B Wait for the system to indicate the end of $DISKUT3 by posting DSK3EVNT. 

01 Set the initial state of the event control block to zero. 

Q Point to the Hst of requests at LISTl. 

01 Point to the specific end-of-data request. 

Q Indicate the end of the Hst of requests. 

Q Request end-of-data (6). 

Q Point to the DSCB for the data set on which to set the end-of-data indicator 
(MASTER on volume EDX003). 

Q Indicate that the last record is full. (If the last record is not yet full, this field 
would contain the number of bytes in the last record.) 

nil Teh $DISKUT3 to return the type of the data set on which the end-of-data 
indicator is being set (0 for undefined, 1 for data, 3 for program). 

Copy the DSCB equates into the program. 
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Performing More Than One Operation at Once 

$DISKUT3 allows you to perform more than one operation during the execution of 
a program. For example, you can delete two data sets and allocate a third without 
loading $DISKUT3 more than once. 



The following example shows how to delete two data sets and allocate one data set. 
An explanation of the numbered items follows the program. 



B 



m 



TASK 


PROGRAM 


GO, DS=((MASTER,EDX0O3), (UPDATE, EDX00 


GO 


EQU 

• 




* 




• 

LOAD 


$DISKUT3 , LISTPTRl , EVENT=DSK3EVNT 




WAIT 

• 


DSK3EVNT 


DSK3EVNT 


• 
ECB 





LISTPTRl 


DC 


A(LISTl) 


LISTl 


DC 


A(REQUESTl) 




DC 


A(REQUEST2) 




DC 


A{REQUEST3) 




DC 


F'O' 


REQUESTl 


DC 


F'4' 




DC 


A(DSl) 




DC 


D'O' 




DC 


F'-r 


REQUEST2 DC 


F'4' 




DC 


A(DS2) 




DC 


D'O' 




DC 


F'-r 


REQUESTS 


DC 


F'2' 




DC 


A(DSA) 




DC 


D'300' 




DC 


FT 




COPY 


DSCBEQU 




DSCB 


DS#=DSA,DSNAME=NEWMAST,VOLSER=EDXO03 




ENDPROG 






END 





'ij 



^kiu-^ 
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B Load $DISKUT3 to delete the data sets MASTER and UPDATE and to 
allocate data set NEWMAST. Specify the address (LISTPTRl) of the Hst of 
requests (in this case, a single request). Identify the event (EVENT = DSK3EVNT) 
to be posted when $DISKUT3 completes. 

B Wait for the system to indicate the end of $DISKUT3 by posting DSK3EVNT. 

Q Set the initial state of the event control block to zero. 

Q Point to the Ust of requests at LISTl. 

B Point to the request to delete data set MASTER. 

B Point to the request to delete data set UPDATE. 

B Point to the request to allocate data set NEWMAST. 

B Indicate the end of the list of requests. 

B Request a delete (4). 

ICT Point to the DSCB for the first data set to be deleted (MASTER on volume 
EDX003). 

This doubleword is not used for delete requests. 

Tell $DISKUT3 to return the type of the data set being deleted (0 for 
undefined, 1 for data, 3 for program). 

IB Request a delete (4). 



Point to the DSCB for the second data set to be deleted (UPDATE on volume 
EDX002). 

IB Request an allocate (2). 

IB Point to the DSCB for the data set to be allocated (NEWMAST). 

Allocate 300 records. 

tlii Indicate that the data set type is data. 

ttl Copy the DSCB equates into the program. 

Bel Define a DSCB for the data set being allocated (NEWMAST on volume 
EDX003). 
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Opening a Data Set (DSOPEN) 



Error Exits 



You can open a disk, diskette, or tape data set from a program with the DSOPEN %^ 

copy code. DSOPEN does the same thing that the system does when you specify a 
data set in the PROGRAM statement and load the program with either the $L 
operator com.mand or the LOAD instruction. 

Note: Only one DSCB can be open to a tape at a time. If you open a tape data set, 
you must close the data set before you can open another tape data set. 

You might use DSOPEN for any of the following reasons: 

• Your program requires more than nine data sets. 

• You do not know, at the time you load a program, whether or not the program 
will need a data set. 

• You need to open a data set and do not want to load $DISKUT3 (the system 
does not need to load DSOPEN). 

• The processor storage that $DISKUT3 requires is not available (DSOPEN 
requires about 1.5K bytes and $DISKUT3 requires about 6.25K bytes). 

DSOPEN performs the following functions: 

• Verifies that the specified volume is online 

• Verifies that the specified data set is in the volume 

• Initializes the DSCB. 

To use DSOPEN, you must first copy the source code into your program by coding: 

COPY TCBEQU 

COPY PROGEQU 

COPY DDBEQU 

COPY DSCBEQU 

COPY DSOPEN 

Note: You must code the equates in the order given. 

During execution, load DSOPEN with the CALL instruction as follows: 
CALL DSOPEN, (dscb) 



If an error occurs while DSOPEN executes, the system transfers control to one of 
several error exit routines. You must define these routines in your program and 
move their addresses to labels that are contained in DSOPEN before you call 
DSOPEN. The routines cannot be subroutines. 



o 
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The labels and their meanings are as follows: 

Label Description 

SDSNFND Data set name not found in directory. If DSOPEN cannot find the 
data set, then it does not fill in the DSCB. 

SDSBVOL Volume not found in disk directory. The system sets the DDB pointer 
in the DSCB to ($DSCBVDE does not equal 0). 

$DSIOERR Read error occurred while DSOPEN was searching the directory. For 
additional information, refer to the READ instruction return codes in 
the Language Reference. 

$$EXIT The address of an EDL instruction which receives control after 

DSOPEN has completed. $$EXIT must be zero to open the device 
directory (SDSCBNAM is $$EDXVOL). $$EXIT must be zero to 
open the volume directory (SDSCBNAM is $$EDXLIB or $$). 

$DSDCEA Address of an area for DSOPEN to store the directory control entry 
(DCE). This label contains a if this area does not exist. 

If you define an error exit routine as a word of zeroes or move a zero to one of the 
labels, DSOPEN transfers control to the next sequential instruction after the CALL 
instruction. 

In the following example the instruction causes control to return to the next 
sequential instruction if DSOPEN cannot find the data set: 

MOVE $DSNFND,LIBEXIT 



LIBEXIT DATA F'O' 

The following instruction causes control to return to the next sequential instruction 
if DSOPEN cannot the volume: 

MOVE SDSBVOL, G 

DSOPEN Considerations 

Note the following considerations when using DSOPEN: 

• You must have a 256-byte work area labeled DISKBUFR in your program as 
follows: 

DISKBUFR DC 128F'0' 

• The DSCB to be opened can be DS1-DS9 or a DSCB defined in your program 
with the DSCB statement. The DSCB must be initialized with a six-character 
volume name in SDSCBVOL and an eight-character data set name in 
SDSCBNAM. 

• If you specify the volume name as six blanks, DSOPEN searches the IPL volume 
for the data set. 
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After DSOPEN completes, #1 contains the number of the directory record 
containing the member entry and #2 contains the displacement within 
DISKBUFR to the member entry. 

The fields $DSCBEND and $DSCBEDB contain the next available logical 
record data, if any, placed in the directory by SETEOD. 

You can open only one data set on any tape volume at a time. 



%^ 



DSOPEN Example 



The following example shows how to open a data set when the data set is not known 
when the program is loaded. Program MAINPGM, the primary task, prompts the 
operator for the data set name and volume and calls secondary task OPENPGM. If 
the operator does not enter the volume name, the program uses the IPL volume. 



MAINPGM PROGRAM START, MAIN=YES 

EXTRN OPENPGM 
START MOVEA #1,DS1 
READDS READTEXT RESPONSE, '@@ENTER DSNAME, VOLUME - ' 

IF (RESPONSE-1,EQ,X'0O', BYTE), THEN 
GOTO READDS 

ENDIF 

MOVE ($DSCBV0L,#1),IPLV0L,(6,BYTE) 

MOVE WHERE, 

FIND C , ' .RESPONSE, 15, WHERE, DSONLY 

MOVE #2, WHERE 

MOVE ($DSCBV0L,#1) , (1,#2) , (6, BYTE) 

MOVE (0, #2), BLANKS, (8, BYTE) 
DSONLY MOVE ($DSCBNAM,#1) , RESPONSE, (8, BYTE) 

CALL OPENPGM, (DSl) 

MOVE CODE, DSl 

IF (CODE, NE,-1), THEN 

PRINTEXT '(PERROR DURING DSOPEN. RETURN CODE = ' 
PRINTNUM CODE 

ELSE 



o 





ENDIF 






PROGSTOP 






COPY 


DSCBEQU 


CODE 


DC 


F'O' 


IPLVOL 


EQU 


* 


BLANK8 


DC 


CL8' 


WHERE 


DC 


F'O' 


RESPONSE 


TEXT 


• ',LENGTH=15 




DSCB 


DS#=DS1,DSNAME=DUMMY 




ENDPROG 






END 
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Q Begin the program at START and identify this task as the primary task 

(MAIN = YES). 

01 Identify as an external entry the subroutine that this task will call. 

B Place the address of the DSCB in register 1. 

Q Prompt the operator for the data set name. When the operator responds, the 
system places the response in RESPONSE. 

Q Test for a null entry. RESPONSE - 1 contains the length of the operator's 
response. 

B Initialize the volume field (DSCB VOL) of the DSCB to blanks. 

Q InitiaUze the comma locator to zero. 

Q Find a comma in the operator's response. If no comma exists, branch to 
DSONLY. 

B Move the position of the comma to register 2. 

IB Move the volume name to the volume field (DSCBVOL) of the DSCB. 

IB Blank the volume name and the comma preceding it. 

IB Move the data set name to the data set name field (DSCBNAM) of the DSCB. 

Ql Call the routine that opens the data set. Pass the address of the DSCB (pointed 
to by DSi) to the subroutine. 

9 Move the return code into CODE. 



If the return code does not indicate successful completion (—1), print an error 
message and the return code. 

IB Process the data set with READ/WRITE instructions. (SDSCBEND contains 
the number of records in the data set.) 



Cause the DSCB equates to be copied into the program. 

3 Reserve storage for the subroutine return code. 

EB Set up a default value for the IPL volume. 

03 Reserve storage for an index to be used in locating the comma. 

1^ Reserve storage for the operator's response. 

Ql Generate a data set control block (DSCB). Give the data set name field 
(DSCBNAM) the temporary name DUMMY. 

Program OPENPGM consists of a subroutine and error exit routines for DSOPEN. 
The subroutine calls DSOPEN. 
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OPENPGM 


PROGRAM 


MAIN=NO 




ENTRY 


OPENPGM 


1 


SUBROUT 


OPENPGM, ADSN 


MOVE 


SAVEl, #1 


; 


MOVE 


SAVE2,#2 


i 


MOVE 


#1,ADSN 




MOVE 


(o,#i),-i 




MOVEA 


$DSNFND, LIBEXIT 




MOVEA 


$DSBVOL, VOLEXIT 


^ 1 


MOVEA 


$DSIOERR,IOEXIT 





CALL 


DSOPEN,ADSN 




GOTO 


RETURN 


jgj LIBEXIT 


EQU 


* 


I 


MOVE 


#1,ADSN 


I 


MOVE 


(0,#1),1 




PRINTEXT 


'@DATA SET NOT FOUND DURING DSOPEN@ 




GOTO 


RETURN 


Q VOLEXIT 


EQU 


* 


I i 


MOVE 


#1,ADSN 


IE 


MOVE 


(0,#1),2 




PRINTEXT 


'^VOLUME NOT FOUND DURING DSOPEN@' 




GOTO 


RETURN 


jH lOEXIT 


EQU 


* 


i 


MOVE 


#1,ADSN 


£ 


MOVE 


(0,#1),3 




PRINTEXT 


'TERROR ENCOUNTERED DURING DSOPEN@' 




GOTO 


RETURN 


31 RETURN 


MOVE 


#1, SAVEl 


5 
i 
5 


MOVE 

RETURN 

COPY 


#2,SAVE2 
TCBEQU 


5 
5 


COPY 


PROGEQU 


COPY 


DDBEQU 


5 


COPY 


DSCBEQU 


5 


COPY 


DSOPEN 


1 DISKBUFR 


DC 


128F'0' 


i SAVEl 


DC 


F'O' 


a SAVE2 


DC 
END 


F'O' 



o 



Q Identify the name of the subroutine as OPENPGM. Specify that it is not the 
main program (MAIN = NO). 

Q Identify the name of the subroutine as an entry. (In conjunction with the 
EXTRN statement in the main program, this statement allows the Hnkage editor to 
resolve external references.) 

B Define a subroutine with the name OPENPGM. Define a parameter (ADSN) 
that is passed by the caUing program. 

Q Save index register 1 . 

Q Save index register 2. 

Q Move the parameter that was passed from the caUing program (the address of 
the DSCB) to register 1. 
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Q Initialize the return code to indicate successful completion (-1). 

Q Move the address of the data-set-not-found routine to the proper error exit 
within DSOPEN. 

Q Move the address of the invalid-volume routine to the proper error exit within 
DSOPEN. 

EQ Move the address of the I/O error routine to the proper error exit within 
DSOPEN. 

Q] Call DSOPEN, passing the address of the DSCB. 

m Indicate the beginning of the data-set-not-found exit routine. 

m Move the address of the DSCB to register 1. 

Ql Move a 1 to the first word of the DSCB, indicating data set not found. 

IQ Indicate the beginning of the invahd- volume exit routine. 

03 Move the address of the DSCB to register 1. 

EQ Move a 2 to the first word of the DSCB, indicating an invalid volume. 

13 Indicate the beginning of the I/O error exit routine. 

EQ Move the address of the DSCB to register 1 . 

1^ Move a 3 to the first word of the DSCB, indicating an I/O error. 

Q] Restore index register 1 . 

03 Restore index register 2. 

1^ Return to the calhng program. 

1^ Cause the TCB equates to be copied into the program. 

H3 Cause the PROGRAM equates to be copied into the program. 

^H Cause the DDB equates to be copied into the program. 

Bl Cause the DSCB equates to be copied into the program. 

^1 Cause the DSOPEN equates to be copied into the program. 

IH Reserve a 256-byte area for DSOPEN. (This area must have the label 
DISKBUFR.) 

B5I Reserve an area in which to save register 1 . 

Bi Reserve an area in which to save register 2. 
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Coding for Volume Independence 

You may code your applications so that they are independent of the volume in 
which they reside. To achieve volume independence, place all programs and data 
sets in a single volume on any system and specify the characters ## in the volume 
name field of any DS = operand or PGMS = operand of the PROGRAM statement. 
(For information on the PROGRAM statement, refer to the Language Reference.) 

You can also insert the volume name from which your program was loaded into any 
DSCB you have coded in your program. If you insert the volume name into a 
DSCB, you must do so before loading $DISKUT3 or calhng in DSOPEN. The 
volume name, a six-byte field, is located in the $PRGVOL field of the program 
header. 

The following example shows a routine that retrieves the volume name and loads 
DSOPEN to open the data set JOURNAL, located in the same volume from which 
the program was loaded. 

COPY TCBEQU 

COPY PROGEQU 

COPY DDBEQU 

COPY DSCBEQU 

COPY DSOPEN 



ENTER TCBGET 


TCBADDR 


MOVE 


#1, TCBADDR 


MOVE 


#2,($TCBPLP,#1) 


MOVEA 


#1,INDS 


MOVE 


($DSCBV0L,#1) , ($PRGV0L,#2) , (6, BYTE) 


CALL 

• 



DSOPEN, (INDS) 


• 
DSCB 


DS#=INDS,DSNAME=JOURNAL 


DISKBUFR DC 


128F'0' 


TCBADDR DC 


F'O' 



Q Get the address of the task control block (TCB). 

Q Move the address of the TCB into register 1 . 

01 Move the address of the program header into register 2. 

Q Move the address of the data set control block (DSCB) into register 1 . 

Q Move the volume into the DSCB. 

B Call DSOPEN, passing the DSCB as a parameter. 

D Define the DSCB. 

Q Define a work area for DSOPEN. 

Q Define an area for the TCB address. 



10-20 SC34-0943 



Performing Data Management from a Program 



Setting Logical End of File (SETEOD) 






%j^ 



The copy code routine SETEOD allows you to indicate the logical end of file on 
disk. If your program does not use SETEOD when creating or overwriting a file, 
the READ end-of-data exception will occur at either the physical or logical end that 
was set by some previous use of the data set. 

The relative record number of the last full physical record is placed in the $$FPMF 
field of the directory member entry (DME). 

Notes: 

1. If the SDSCBEDB field is zero, the $$FPMF field is set to the next record 
pointer field (SDSCBNEX) minus one. 

2. If the $DSCBEDB field is not zero, the $$FPMF field is set to the SDSCBNEX 
minus two. 

If the last physical record is partially filled, the number of bytes contained in this 
record is placed in the $$FPMD of the DME. Otherwise, a zero is placed in this 
field. (This is done by copying the $DSCBEDB field of the DSCB directly into the 
DME.) (Further information on the DME can be found in the Internal Design.) 

If the next record pointer field ($DSCBNEX) in the DSCB is 1 when SETEOD is 
executed, the DME is set to indicate that the data set is empty and $DSCBEND is 
set to X ' FFFF ' indicating that the data set is empty. If $DSCBEOD is zero, the 
data set is unused. 

SETEOD can be used before, during, or after any READ or WRITE operation. It 
does not inhibit further I/O and can be used more than once. The only requirement 
is that the DSCB passed as input must have been previously opened. 

The POINT instruction modifies the SDSCBNEX field. If SETEOD is used after a 
POINT instruction, the new value of $DSCBNEX is used by SETEOD. 

SETEOD requires that the DSOPEN copy code, PROGEQU, TCBEQU, DDBEQU, 
and DSCBEQU be copied in your program. 

To use SETEOD, copy the source code into your program and allocate a work data 
set as follows: 

COPY TCBEQU 

COPY PROGEQU 

COPY DDBEQU 

COPY DSCBEQU 

COPY DSOPEN 

COPY SETEOD 

DISKBUFR DC 128F'0' WORK AREA FOR DSOPEN 
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Load SETEOD as a subroutine through the Event Driven Language CALL 
statement, passing the DSCB and an I/O error exit routine pointer as parameters. 

CALL SETEOD, (DS1),(I0ERR0R) 



wtiere: 

DSl 

lOERROR 



Names a previously opened DSCB 

Names the routine in the apphcation program to which control is 
passed if an I/O error occurs 



The following program writes a record three times and then sets the logical end of 
file. If an I/O error occurs, the system prints the message "I/O ERROR 
OCCURRED" and then prints a return code. 



SET 



START 



lOERROR 



DATA 

DISKBUFR 
a BUFF 
RC 



PROGRAM 

PRINT 

COPY 

COPY 

COPY 

COPY 

COPY 

COPY 

PRINT 

EQU 

MOVE 

DO 

WRITE 

ENDDO 

CALL 

PROGSTOP 

EQU 

TCBGET 

PRINTEXT 

PRINTEXT 

PRINTNUM 

PROGSTOP 

DC 

DC 

BUFFER 

DATA 

ENDPROG 

END 



START, DS=( (ANY, EDX0O3)) 

OFF 

TCBEQU 

PROGEQU 

DDBEQU 

DSCBEQU 

DSOPEN 

SETEOD 

ON 

* 

BUFF, DATA, (256, BYTES) 

3, TIMES 

DSl, BUFF, 1,ERROR=IOERROR 

SETEOD, (DSl), (lOERROR) 



RC,$TCBCO 

'I/O ERROR OCCURRED ',SKIP=1 

'ERROR RETURN CODE=' 

RC,SKIP=1 

256C'A' 
128F'0' 
256, BYTES 
F'O' 



\J 



o 
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Q Copy the TCB equates into the program. 

Q Copy the PROGRAM equates into the program. 

Q Copy the DDB equates into the program. 

Q Copy the DSCB equates into the program. 

Q Copy the DSOPEN routine into the program. 

Q Copy the SETEOD routine into the program. 

Q Indicate the beginning of the executable instructions. 

01 Move 256 bytes of data into the buffer area. 

Q Indicate the beginning of a DO loop. 

fH^ Write 1 record to the data set ANY on volume EDX003 from the buffer with 
the label BUFF. 

m End the loop. 



Call the subroutine SETEOD to set the end of data on the data set ANY on 
volume EDX003. If an error occurs transfer control to lOERROR. 

IM End program execution. 

03 Indicate the beginning of the error routine. 

IQ Obtain the return code from the first word of the task control block (TCB) and 
place it in RC. 

[Q Print the message "I/O ERROR OCCURRED." 

Print the message "ERROR RETURN CODE = ." 



EQ Print the return code. The return code indicates the type of I/O error the 
system encountered. 

itl End program execution. 

EBl Define a 256-byte storage area labeled DATA. 

131 Reserve a 256-byte work area for DSOPEN. This area must be labeled 
DISKBUFR. (This is a requirement for DSOPEN.) 

BBI Define a 256-byte storage area labeled BUFF. 

Ql Reserve a data area for RC (the I/O error return code). 
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Finding the Device Type (EXTRACT) 



The inline copy code routine EXTRACT determines the device type from the device 
descriptor block. This routine is provided for appHcations that are sensitive to 
device type. For example, an apphcation may need to allocate a data set unless the 
data set were to reside on a tape. Before attempting to execute instructions that 
would not execute successfully, the EXTRACT routine can be used to determine the 
device type. 

To use EXTRACT, you must copy the source code into your program. The routine 
requires the address of a DSCB in #1 and returns the device type in #1. 

MOVEA #1,DS1 

COPY EXTRACT 

IF (#1,EQ,X'3186'),G0T0,TAPEDS 

In this example, X'3186' is the device ID of an IBM 4969 Magnetic Tape. 

To get a list of the device IDs on your system, use the LD command of the 
SIOTEST utihty. 
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^ Chapter 11. Reading and Writing to Tape 



This chapter describes the tape facihties you can use when using tape as part of your 
EDL program. 

For information on how to allocate tape data sets, copy data sets from one medium 
to another, and change tape attributes, refer to the STAPEUTl utility in the 
Operator Commands and Utilities Reference or the Operation Guide. 

For more information on how to access magnetic tape data sets, refer to the 
Language Reference. 

For information on data set naming conventions, see "Specifying Data Sets" on 
page 6-3. 



What Is a Standard-Label Tape? 






A standard-label tape consists of data sets separated by 80-character label records 
and tapemarks. 

A label record is a record that the system writes on a tape to do such things as 
identify the volume, indicate the beginning of a data set, and indicate the end of a 
data set. 

Standard label tapes contain a volume label (VOLl) and a header label (HDRl) 
before each data set and a trailer label (EOFl) after each data set. For the contents 
of the labels, see Appendix A, "Tape Labels." 

A tapemark is a control character that the system writes on a tape. The hardware 
uses tapemarks to recognize such things as the beginning or end of a data set. 

You would use standard-label tapes to maintain data security or to control an 
extensive library of tapes. 



What Is a Nonlabeled Tape? 



A nonlabeled tape consists of data sets separated only by tapemarks. Nonlabeled 
tapes allow you to read tapes that have unknown record length or an unknown 
label. You would use nonlabeled tapes if you do not need to maintain strict data 
security or if you use only a small number of tapes. 
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Processing Standard-Label Tapes g-^ 

m I ) 
This section describes how to: ""Iw^ 

• Read a standard-label tape 

• Write a standard-label tape 

• Close a standard-label tape 

• Bypass standard labels 

• Process a tape containing more than one data set. 

Reading a Standard-Label Tape 

The READ instructions allows you to retrieve a record from 18 to 32767 bytes long. 

In the following example: 
TASK04 PROGRAM START, DS=(UPDATES, (MASTER, 56390)) 



READ DS2, BUFF, 1, 120, END=NMRCDS,ERROR=OOPS,WAIT=YES 



BUFF DATA 60F'O' 

the system reads one record (indicated by 1 in the third operand) from the second 
file listed on the PROGRAM statement (data set MASTER on volume serial 56390) 
into BUFF. (The term volume serial means the same as the term volume.) 

The size of the record is 120 bytes (indicated by 120 in the fourth operand). If no 
more records exist on the data set, control transfers to NMRCDS. If an error 
occurs, control transfers to OOPS. The system waits (WAIT = YES) for the read 
operation to complete before executing the next sequential instruction. 

The following READ instruction reads 2 records into BUFF2. BUFF2 must be 654 
bytes long. 

TASK37 PROGRAM BEGIN,DS=( (UPDATES, 73499) , (MASTER, 56390)) 



READ DS1,BUFF2,2,327,END=END1,ERR0R=ERR,WAIT=YES 



BUFF2 DATA 327F'G' 

The system reads two records (indicated by 2 in the third operand) from the first 
data set (UPDATES on volume serial 73499) hsted on the PROGRAM statement. 
The size of the record is 327 bytes (indicated by 327 in the fourth operand). If no 
more records exists on the data set, control transfers to ENDl. If an error occurs, 
control transfers to ERR. The system waits (WAIT = YES) for the read operation to 
complete before executing the next sequential instruction. 






o 
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Writing a Standard-Label Tape 

The WRITE instruction allows you to write a record from 18 to 32767 bytes long. 

In the following example: 
TASK04 PROGRAM START, DS=(UPDATES, (MASTOUT, 00032)) 



WRITE DS2, BUFF, 1, 120, ERROR=GOOF,WAIT=YES 



BUFF DATA 60F'0' 

the system writes one record (indicated by 1 in the third operand) to the second file 
listed on the PROGRAM statement (data set MASTOUT on volume serial 00032) 
from BUFF. The size of the record is 120 bytes (indicated by 120 in the fourth 
operand). If an error occurs, control transfers to GOOF. The system waits 
(WAIT = YES) for the write operation to complete before executing the next 
sequential instruction. 

The following WRITE instruction writes 2 records from BUFF2. BUFF2 must be 
656 bytes long. 

TASK74 PROGRAM BEGIN,DS=( (DATES, 28345) , (MASTER, 56390)) 



WRITE DS1,BUFF2,2,328,ERR0R=ERR0R,WAIT=YES 



BUFF2 DATA 328F'0' 

The system writes two records (indicated by 2 in the third operand) to the first data 
set (DATES on volume serial 28345) Hsted on the PROGRAM statement. The size 
of the record is 328 bytes (indicated by 328 in the fourth operand). If an error 
occurs, control transfers to ERROR. The system waits (WAIT = YES) for the read 
operation to complete before executing the next sequential instruction. 

Note: To write an uneven number of bytes to a 4969 Tape Unit, you must have the 
latest Engineering Changes installed on the device. 
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Closing Standard-Label Tapes 

Whether you read or write a standard-label tape, you should close the tape data set 
when you finish reading or writing. Closing a tape data set causes the system to 
write trailer labels. Use the CONTROL instruction to close a tape data set as 
follows: 

TASK98 PROGRAM BEGIN, DS=((DATES, 28345) , (MASTER, 56390)) 



CONTROL DS1,CLS0FF 



The system closes the first data set (DATES on volume serial 28345) Hsted on the 
PROGRAM statement. CLSOFF causes the system to rewind the tape and set the 
tape drive offline. 

For information on other ways to close a tape, refer to the Language Reference. 

Bypassing Labels 

If you want to bypass the labels on a standard-label tape, you must have defined a 
tape drive as BLP during system generation or changed the label processing attribute 
with the $TAPEUT1 utihty. For information on defining a BLP drive, refer to the 
Installation and System Generation Guide. 

The following sample program shows how to bypass standard labels. 

B PR0G8 PROGRAM START,DS=((XYZ,TAPE01)) 

START EQU * 

n READ DSl, BUFFER,!, 80, ERR0R=ERR1 

y READ DSl, BUFFER,!, 80, ERR0R=ERR1 

B CONTROL DS1,FSF 

LOOP EQU * 

B READ DSl, BUFFER,!, 50, ERR0R=ERR2,END=ALLD0NE 

GOTO LOOP 

ALLDONE EQU * 



B 




READ DSl, BUFFER,!, 80, ERR0R=ERR1 




ENDIT 


EQU 
PROGSTOP 




ERR! 


EQU * 

PRINTEXT 'QLABEL ERROR - RC= ' 

PRINTNUM DSl 

GOTO ENDIT 




ERR2 


EQU * 

PRINTEXT '(SREAD ERROR - RC= ' 
PRINTNUM DSl 

QUESTION '000 YOU WANT TO CONTINUE? ' 
YES=LOOP,NO=ENDIT 




BUFFER 


DATA 40F'0' 

ENDPROG 

END 
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Q Identify the tape as data set XYZ on tape ID TAPEOl. The system ignores the 
data set name but you must supply it. 

B Read the first of the standard label records (the VOLl label) into BUFFER. 
(You can insert instructions after this instruction to process the label.) 

B Read the second of the standard label records (the HDRl label) into BUFFER. 
(You can insert instructions after this instruction to process the label.) 

Q Forward space the file one tapemark. This instruction causes the system to skip 
any remaining blocks in the header and position itself at the first record of the file. 

B Process the data. This instruction reads a 50-character record (indicated by 50 
in the third operand) into BUFFER. If an error occurs, control transfers to ERR2. 
If no more records exist on the data set, control transfers to ALLDONE. 

B Read the trailer label (the EOFl label) into BUFFER. You can insert 
instructions after this instruction to process the label. 

Processing a Tape Containing IVIore than One Data Set 

To process a tape that contains more than one data set, use the SVARYON operator 
command to position the tape to the data set you want to read. For example, to 
position a tape at address 4C to the fourth data set, issue the following command: 



> $VARYON 4C 4 



The system responds as follows: 



TAPEOl ONLINE 
v. 



TAPEOl is the ID that was assigned to the tape drive at system generation. 

After you use the SVARYON operator command, you can process the data set as 
you would any other tape data set. 
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Reading a Multivolume Data Set 

To read a multivolume data set, you must add instructions to your program to 
process the data set. The following program reads a multivolume data set. 



Q PROGX 


PROGRAM 


START, DS=?? 


START 


EQU 


* 


B 


READ DSl, BUFFER,!, 803 ERR0R=ERR1,END=CHKEND 

• 





• 
GOTO 


START 


ENDIT 


EQU 
PROGSTOP 


* 


CHKEND 


EQU 


* 




CONTROL 


DS1,CLS0FF 




IF (DS1,EQ,33) 




PRINTEXT 


■eEOV ENCOUNTERED - ENTER VOLl OF NEXT VOLUME© 




READTEXT 


NEWVOL 




MOVEA #1 


,DS1 




MOVE ($DSCBV0L,#1) , NEWVOL, (3, WORD) 




MOVEA $DSNFND, ERRDSN 




MOVEA 


SDSBVOL, ERRVOL 




MOVEA 


$DSIOERR, ERRIO 


ED 


QUESTION 


'(9REPLY Y WHEN NEXT VOLUME MOUNTED AND ONLINE? 




NO 


=ENDIT 


fO 


CALL DS0PEN,(DS1) 


la 


GOTO 


START 




ENDIF 






GOTO 


ENDIT 


ERRDSN 


EQU 


* 




MOVEA 


MSGX,MSG1 




GOTO 


ERRMSG 


ERRVOL 


EQU 


* 




MOVEA 


MSGX,MSG2 




GOTO 


ERRMSG 


ERRIO 


EQU 


* 




MOVEA 


MSGX,MSG3 


ERRMSG 


EQU 


* 




PRINTEXT 


■@DSOPEN ERROR -0' 




PRINTEXT 


MSG1,P1=MSGX 




PRINTEXT 


SKIP=1 




GOTO 


ENDIT 


MSGl 


TEXT 


'DATA SET NOT FOUND' 


MSG2 


TEXT 


'VOLUME NOT FOUND' 


MSG3 


TEXT 


'I/O ERROR' 


ERRl 


EQU 


* 




PRINTEXT 


'@READ ERROR - RC=' 




PRINTNUM 


DSl 




GOTO 


ENDIT 


BUFFER 


DATA 


40F'0' 80 BYTE BUFFER 


NEWVOL 


TEXT 


HOLDS NEW VOLUME # 


REPLY 


TEXT 


LENGTH=2 




COPY 


DSOPEN 




COPY 


DSCBEQU 




COPY 


PROGEQU 




COPY 


DDBEQU 


DISKBUFR 


DC 
ENDPROG 


128F'0' 






END 
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Q Cause the system to issue a prompt for the data set name and volume of the 
input data set. 

Q Read an 80-character record into BUFFER. If an error occurs transfer control 
to ERRl. If no more records exist, transfer control to CHKEND. 

Q Close the input data set, rewind the tape, and set the tape drive offline. 

Q Test for a return code of 33, indicating that the system found an end-of- volume 
label. 

Q Prompt the operator for the volume serial of the next tape. 

01 Read the volume serial into NEWVOL. 

Q Move the address of the DSCB for the data set into software register 1. 

Move the volume serial into the $DSCBVOL field of the DSCB. 

Q Set the DSOPEN error exits in this instruction and in the next two instructions. 
03 Prompt the operator for a response when he/she has mounted the tape. 

01 Call the DSOPEN routine to open the next volume of the data set. 
Resume processing the data. 



Processing Nonlabeled Tapes 

This section describes how to: 

• Define a nonlabeled tape 

• Initiahze a nonlabeled tape 

• Read a nonlabeled tape 

• Write a nonlabeled tape. 
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Defining a Nonlabeied Tape 

To read and write from a nonlabeied tape, you must define the drive as nonlabeied. 
If the tape drive hasn't already been defined as nonlabeied, you must: 

1 Vary the tape drive offline. 

2i Change the label processing attribute to nonlabeied using the $TAPEUT1 
utiUty. 

J Vary the tape drive online. 
To vary the tape drive offline, use the SVARYOFF operator command as follows: 



'%i„.^ 



> SVARYOFF 4C 
TAPE01 OFFLINE 



The command varies offline the tape drive at address 4C. TAPEOl is the ID that 
was assigned during system generation. 

The following example shows how to use the $TAPEUT1 utility to change the label 
processing attribute: 



> $L STAPEUTl 



COMMAND (?) CT 

ENTER TAPEID (1-6 CHARS): TAPEOl 
TAPE TAPEOl AT ADDR 4C is SL 1600 BPI 

DO YOU WISH TO MODIFY?: Y 

LABEL {NULL,SL,NL,BLP)?: NL 
DENSITY (NULL, 800, 1500)?: 800 

TAPE TAPEOl AT ADDRESS 4C IS NL 800 BPI 

COMMAND ? EN 



o 



This example changes tape TAPEOl to nonlabeied 800 bytes per inch. 

To vary the tape drive online, use the SVARYON operator command as follows: 



> SVARYON 48 

TAPEOl ONLINE 



v.. 



The command varies onhne the tape drive at address 48. TAPEOl is the ID that was 
assigned during system generation. 
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Initializing a Nonlabeled Tape 

To initialize a nonlabeled tape, you must: 



1 Vary the tape drive offline. 

2 Initialize the tape. 

J Vary the tape drive online. 
To vary the tape drive offline, use the SVARYOFF operator command as follows: 



> $VARYOFF 4C 

TAPE01 OFFLINE 






The command varies offline the tape drive at address 4C. TAPEOl is the ID that 
was assigned during system generation. 

To initialize the tape, use the STAPEUTl utiUty as follows: 



> $L $TAPEUT1 

COMMAND (?) IT 

TAPE ADDR (1 - 2 HEX CHARS): 4C 

NO LABEL 800 BPI? Y 

TAPE INITIALIZED 

COMMAND ? EN 

To vary the tape drive onUne, use the $VARYON operator command as follows: 



> $VARYON 4C 

TAPEOl ONLINE 



The command varies onhne the tape drive at address 4C. TAPEOl is the ID that 
was assigned during system generation. 
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Reading a Nonlabeled Tape 

The READ instructions allows you to retrieve a record from a nonlabeled tape. The 
records can be from 18 to 32767 bytes long. 

In the following example: 
TASK04 PROGRAM START, DS=(UPDATES, (MASTER, TAPEOl)) 



READ DS2, BUFFER, 1,8G,END=N0M0RE,ERR0R=ERR0R,WAIT=YES 



BUFFER DATA 60F'0' 

the system reads one record (indicated by 1 in the third operand) from the second 
file hsted on the PROGRAM statement (data set MASTER on tape ID TAPEOl) 
into BUFFER. The size of the record is 80 bytes (indicated by 80 in the fourth 
operand). If no more records exist on the data set, control transfers to NOMORE. 
If an error occurs, control transfers to ERROR. The system waits (WAIT = YES) 
for the read operation to complete before executing the next sequential instruction. 

Writing a Nonlabeled Tape 

The WRITE instruction allows you to write a nonlabeled record from 18 to 32767 
bytes long. 

In the following example: 
TASK04 PROGRAM START, DS=(UPDATES, (MASTOUT, TAPEOl)) ^^ 



WRITE DS2, BUFF, 1, 120, ERROR=GOOF,WAIT=YES 



BUFF DATA 60F'0' 

the system writes one record (indicated by 1 in the third operand) to the second file 
listed on the PROGRAM statement (data set MASTOUT on tape ID TAPEOl) 
from BUFF. The size of the record is 120 bytes (indicated by 120 in the fourth 
operand). If an error occurs, control transfers to GOOF. The system waits 
(WAIT = YES) for the write operation to complete before executing the next 
sequential instruction. 



^itau/r 
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Adding Records to a Tape File (UPDATE) 



The copy code routine UPDTAPE allows you to add records to an existing (or new) 
tape file. The records added are placed after existing records on the file. On 
standard label tapes, the routine updates the block count counters in the EOFl label. 

To use UPDTAPE, you must copy the source code into your program by coding: 
COPY UPDTAPE 

You load UPDTAPE as a subroutine through the CALL instruction, passing the 
DSCB as a parameter. 

CALL UPDTAPE, (DSl) 

where DSl is a previously opened DSCB. 

After the CALL, you must check the return code in the first word of the DSCB for 
the tape motion return codes. A — 1 return code indicates that the tape is positioned 
correctly for writing records. 
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The following example adds 1000 records to a tape data set. The program prompts 
the operator for the data set name and volume. 

Q UPDTAP PROGRAM START, DS=((TAPEDS,??)) \^ 

START EQU * 



n CALL UPDTAPE,(DS1) 



I 



IF (DS1,NE,-1) 

PRINTEXT 'TERROR - UPDTAPE RC =' 

PRINTNUM DSl 

PRINTEXT SKIP=1 

GOTO ENDIT 
ENDIF 
DO 1000, TIMES 

WRITE DSl, BUFF, ERR0R=ERR 

ADD BUFFNUM,1 
ENDDO 
ENDIT EQU * 

IF (DS1,EQ,-1) 

PRINTEXT '@TAPE UPDATED SUCCESSFULLY©' 

CONTROL DS1,CLSRU 

IF (DS1,NE,-1) 
PRINTEXT 'eCLOSE ERROR - RC =' 
PRINTNUM DSl 



PRINTEXT SKIP=1 


ENDIF 




ENDIF 




PROGSTOP 




ERR EQU 


* 


PRINTEXT 


'(3WRITE ERROR 


PRINTNUM 


DSl 


PRINTEXT 


SKIP=1 


GOTO 


ENDIT 


BUFF DC 


127X'FFFF' 


BUFFNUM DC 


FT 


COPY 


DSCBEQU 


COPY 


TDBEQU 


COPY 


DDBEQU 


COPY 


UPDTAPE 


ENDPROG 




END 





RC =' 



Q Cause the system to prompt for the name and volume of the tape data set. 

01 Call the subroutine, passing the DSCB as a parameter. 

01 Check the return code from the subroutine. 

Q Add 1000 records to the tape data set. 

01 Write a record to the data set from buffer BUFF. If an error occurs, branch to 
ERR. 



f^ 
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Chapter 12. Communicating with Another Program 
(Cross-Partition Services) 

To communicate with another program, you can use cross-partition services. 
Cross-partition services require synchronization logic in your programs but no 
additional storage in the supervisor. 

Communication is possible between two programs within the same partition and 
between programs in different partitions. Cross-partition services permit 
asynchronous but coordinated execution of application programs running in different 
partitions. 

Use these services when interrelated programs and tasks in your apphcation cannot 
be accommodated in a single partition. 

When your task is attached, its TCB ($TCBADS) is updated to contain the number 
of the address space in which it is executing. The address space value (the partition 
number minus one) is also known as the hardware address key. This key, along with 
an address you supply, is used to calculate the target address used in cross- partition 
services. For some functions, you put the address key of the target partition in 
STCBADS. 

The following sections contain examples of the different uses of the cross-partition 
services. 



Chapter 12. Communicating with Another Program (Cross-Partition Services) 12-1 



Communicating with Another Program (Cross-Partition Services) 



Loading Other Programs 



In the following example, PROGA loads PROGB into partition 2 and passes the 
parameters at PROGASWl to it. When PROGB terminates, the supervisor posts 
the ECB at END WAIT, signaling PROGA that PROGB has ended. 

In this example, the system queues the program loaded (PROGB) to the terminal 
that is enqueued by the loading program (PROGA). 

$TCBADS is not modified by the LOAD instruction. PROGA, the loading 
program, looks hke this: 

B PROGA PROGRAM START, 1,MAIN=YES 
ATLIS ATTNLIST (CA.PROGASTP) 
PROGASTP EQU * 

BMOVE #1, PROGASWl 
MOVE (0,#1),1,TKEY=1 
ENDATTN 
START EQU * 
Q TCBGET PROGAKEY,$TCBADS 

y LOAD PROGB, PROGASWl, EVENT=ENDWAIT,LOGMSG=YES, PAR T=2 
B IF (PROGA, EQ,-1), THEN 
WAIT ENDWAIT 
ELSE 

PRINTEXT 'LOAD FAILED' ,SKIP=1 
ENDIF 
PROGSTOP 
ENDWAIT ECB 

PROGASWl DATA A (PROGASWl) 
PROGAKEY DATA F'O' 
ENDPROG 
END 

Notes on PROGA are as follows: 

Q Define the primary task (MAIN = YES). Assign priority 1 to the task. 

01 Define an attention-interrupt-handhng routine. When the operator enters "CA" 
and presses the attention key, branch to PROGASTP. 

Q Move PROGASWl into register 1. (When this instruction executes, 
PROGASWl contains the address of CANCELSW in PROGB.) 

Q Move 1 to address (0,#1). Indicate the address key of the loaded program 
(TKEY= 1). Address (0,#1) points to the address of CANCELSW. In PROGB, the 
IF instruction finds that CANCELSW contains a 1 and passes control to the label 
STOP. 

B Put PROGA's address key into PROGAKEY. 

Q Load PROGB, passing the parameters beginning at label PROGASWl. Identify 
the event to be posted when PROGB completes (EVENT = ENDWAIT), indicate 
that the PROGRAM LOADED message is to appear on the terminal, and load the 
program into partition 2 (PART= 2). 

B If PROGB loads successfully, wait for PROGB to post the event ENDWAIT. 
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The following program, PROGB, is the program being loaded. 

When the operator presses the attention key and enters "CA," the 
attention-interrupt-handUng routine at label CANCEL in PROGA begins executing. 

Q PROGB PROGRAM START, 509, PARM=2 

START EQU * 

B PRINTEXT 'TO CANCEL HIT > CA',SKIP=1 

PRINTEXT SKIP=1 
MOVEA PROGAWRK,CANCELSW 
MOVE #1,$PARM1 

MOVE (0,#1),PROGAWRK,TKEY=$PARM2 

13 LOOP IF (CANCELSW,EQ,1), GOTO, STOP 

GOTO LOOP 

STOP EQU * 

Q PROGSTOP -1,L0GMSG=N0 

PROGAWRK DATA F'O' 
CANCELSW DATA F"0' 
ENDPROG 
END 

Q Specify the length of the parameter list that PROGB receives from PROGA 
(PARM = 2). The system recognizes each word in the parameter Ust by the label 
$PARMx, where "x" indicates the position of the word in the list. $PARM1 refers 
to the first word in the hst (PROGASWl) and $PARM2 refers to the second word 
in the list (PROGAKEY). 

01 Display a prompt that tells the operator how to cancel PROGB. 

B Move the address of CANCELSW into PROGAWRK. 

Q Move the first parameter (the address of PROGASWl) into software register 1. 

B Move the contents of PROGAWRK to the address (0,#1) in PROGA. The 
TKEY operand of the MOVE instruction supphes the address key of PROGA. 

Q Loop until the operator cancels the program. 

B Post the loading program (PROGA) with a - 1. Suppress the PROGRAM 
ENDED message (LOGMSG = NO). 

Note: When you execute a LOAD instruction for any type of program, the default 
terminal address or the currently active terminal address of the program issuing the 
LOAD is placed in the program header of the loaded program. This address is 
taken from $PRGCCB in the issuing program's program header and placed into 
SPRGCCB of the loaded program's program header. This address is a CCB 
address. 
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Finding Other Programs 



The following example uses the WHERES instruction to find another program and 
return the address key and the load point of a program. 

Q WHERES PROGB,ADDRB,KEY=KEYB 



y PROGB DATA C'PROGB 
y ADDRB DATA F'O' 
y KEYB DATA F'O' 

Q Find program PROGB. Put the load point address in ADDRB and the address 
key in KEYB. 

Q Define the program to be found (the name you give the program when you 
hnk-edit it). 



Q Define storage for the load-point address. 
Q Define storage for the address key. 



Starting Other Tasics 

You can start a task in another partition with the ATTACH instruction. (I J 

In the following example, PROGA starts (or "attaches") the task labeled 
TASKADDR in PROGB. 



I 



PROGA 



START 



PROGRAM 


START 


COPY 


PROGEQU 


COPY 


TCBEQU 


EQU 


* 


WHERES 


PROGB, ADDRB, KEY=KEYB 


IF 


(PROGA, EQ,0), THEN 


PRINTEXT 'PROGRAM NOT FOUND', SKI P= 


GOTO 


DONE 


ENDIF 




TCBGET 


SAVEKEY,$TCBADS 


TCBPUT 


KEYB,$TCBADS 


ADD 


ADDRB,X'34' ,RESULT=TASKADDR 


ATTACH 


*,P1=TASKADDR 


TCBPUT 


SAVEKEY,$TCBADS 



DONE PROGSTOP 
SAVEKEY DATA F'O' 
[Q PROGB DATA C ' PROGB 
ADDRB DATA F'O' 
KEYB DATA F'O' 

ENDPROG 

END 



o 
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Q Copy the PROGRAM equates into the program. 

Q Copy the task control block (TCB) equates into the program. 

Q Find the load-point address and address key of PROGB. Place the load-point 
address of PROGB into ADDRB and the address key of the program into KEYB. 

Q If the WHERES instruction returns a zero, indicating an error, print an error 
message and end the program. 

B Save PROGA's address key in SAVEKEY. 

Q Move PROGB's address key to the address key field (STCBADS) of the TCB. 

B Add X ' 34 ' to the load point of PROGB. Put the result of the addition in 
TASKADDR. (PROGA assumes that PROGB defines the task to be attached 
immediately after the PROGRAM statement. The PROGRAM statement generates 
52 bytes (X' 34') of code.) 

B Attach the task. Assume that the address of the task to be attached is contained 
in TASKADDR (calculated by the ADD instruction). 

B Restore PROGA's address key from SAVEKEY. 

n»l Indicate the name of the program to be found. (The name of the program is 
the name assigned to it when the program was hnk edited.) 

The following program contains task NEXT that PROGA attaches. This program 
must be in storage when PROGA issues the WHERES instruction. 

PROGB PROGRAM START 



n TASKADDR TASK NEXT 



I 



NEXT ENQT $SYSPRTR 

PRINTEXT '©SUBTASK IS ATTACHED' 



DEQT 
ENDTASK 
START EQU * 

PRINTEXT '@PROGB STARTED' 
WAIT KEY 



PROGSTOP 

ENDPROG 

END 
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D Define a task with the name TASKADDR. 



Enqueue the system printer (SSYSPRTR). 






B Print the message PROGB STARTED. 

Q Wait for the operator to press the enter key. (The example assumes that the 
operator will not press the enter key until the task labeled TASKADDR in PROGB 
has executed.) 

Note: When you issue an ATTACH instruction, the system stores the address of the 
terminal from which the main task was loaded in the $TCBCCB field of the attached 
task. In this way, the same terminal is active for both tasks. 



Sharing Resources with the ENQ/DEQ Instructions 

You can share serially-reusable resources with programs in other partitions by using 
the ENQ and DEQ instructions. 

In the following example, SQROOT is a subroutine that has been link edited by 
several other programs. The subroutine is serially reusable because only one 
program can use the subroutine at a time. PROGA attempts to enqueue the queue 
control block (QCB) in PROGB. PROGA must enqueue the QCB before it can call 
the subroutine labeled SQROOT. 



PROGA 


PROGRAM 


START 


D 


COPY 


TCBEQU 


B 


EXTRN 


SQROOT 


START 


EQU 


* 


B 


WHERES 


PROGB, ADDRB, KEY=KEYB 


H 


IF 


(PROGA, EQ,0), THEN 




PRINTEXT 'PROGRAM NOT FOUND' ,SKIP=1 




GOTO 


DONE 




ENDIF 




1 


TCBGET 


SAVEKEY, $TCBADS 


• 


TCBPUT 


KEYB,$TCBADS 




ADD 


ADDRB,X'34' ,RESULT=PROGBQCB 




ENQ 


* , BUSY=CANTHAVE , P1=PR0GBQCB 




CALL 


SQROOT 


1 


MOVE 


PRGBQCB,PR06BQCB 


1 


DEQ 


*,P1=PRGBQCB 


3 


TCBPUT 


SAVEKEY, $TCBADS 




GOTO 


DONE 


CANTHAVE 


EQU 


* 




PRINTEXT 


'^RESOURCE BUSY' 




TCBPUT 

• 
9 


SAVEKEY, $TCBADS 


DONE 


• 
PROGSTOP 




SAVEKEY 


DATA 


F'O' 


IH PROGB 


DATA 


C PROGB ' 


ADDRB 


DATA 


F'O' 


KEYB 


DATA 

ENDPROG 

END 


F'O' 



\) 



o 
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Q Copy the task control block (TCB) equates into the program. 

01 Identify the subroutine as an external entry (to be resolved at link-edit time). 

Q Find the load-point address and address key of PROGB. Place the load-point 
address of PROGB into ADDRB and the address key of the program into KEYB. 

Q If the WHERES instruction returns a zero, indicating an error, print an error 
message and end the program. 

B Save PROGA's address key in SAVEKEY. 

Q Move PROGB's address key to the address key field (STCBADS) of the TCB. 

B Add X'34' to the load point of PROGB. Put the result of the addition in 
PROGBQCB. PROGA assumes that PROGB defines the queue control block 
(QCB) immediately after the PROGRAM statement. The PROGRAM statement 
generates 52 bytes (X'34') of code. 

B Enqueue the subroutine. Assume that the address of the task to be attached is 
contained in PROGBQCB (calculated by the ADD instruction). 

B Call the SQROOT subroutine. 

IBl Move the contents of PROGBQCB to PRGBQCB. 

[Q Dequeue the queue control block (PRGBQCB). 

IB Restore PROGA's address key from SAVEKEY. 

IB Indicate the name of the program to be found. (The name of the program is 
the name assigned to it when the program was link edited.) 

The subroutine hnk edited with PROGA looks hke: 

SUBROUT SQROOT 
ENTRY SQROOT 
PRINTEXT '©SUBROUTINE HAS BEGUN' 



RETURN 
END 

PROGB could look like this: 

PROGB PROGRAM START 
QCBl QCB 
START EQU * 
B WAIT KEY 

PROGSTOP 

ENDPROG 

END 

B Wait for an operator to press the enter key. (The program contains the QCB 
and should remain active while other programs in the system are using the SQROOT 
subroutine.) 
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Synchronizing Tasics in Other Partitions 



You can synchronize two or more tasks in different partitions with the WAIT and 
POST instructions. The following programs show how to issue a POST instruction 
to a program in another partition. 



'\,.^ 



The first program, PROG A, finds the second program, PROGB, finds its event 
control block (ECB), and posts the ECB. In this example, PROGB must be loaded 
before PROGA. 

PROGA assumes that PROGB contains an ECB immediately following the 
PROGRAM statement. 



I 



B 



PROGA 


PROGRAM 


START 




COPY 


TCBEQU 


START 


EQU 


* 




WHERES 


PROGB, ADDRB, KEY=KEYB 




IF 


(PROGA, EQ,0), THEN 




PRINTEXT 


'PROGRAM NOT FOUND' 




GOTO 


DONE 




ENDIF 






TCBGET 


SAVEKEY, $TCBADS 




TCBPUT 


KEYB,$TCBADS 




ADD 


ADDRB, X'34' ,RESULT=PGMBECB 




POST 


*,-l,Pl=PGMBECB 




MOVE 


SAVEKEY, $TCBADS 


DONE 


PROGSTOP 




ROGB 


DATA 


C'XP12B ' 


SAVEKEY 


DATA 


F'O' 


ADDRB 


DATA 


F'O' 


KEYB 


DATA 

ENDPROG 

END 


F'O' 



,<~^, 

^ 
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Q Copy the task control block (TCB) equates into the program. 

Q Find the program defined at PROGB, put the address of the program in 
ADDRB, and put the address key of the program in KEYB. 

Q If the WHERES instruction returns a zero, print an error message and end the 
program. 

D Save PROGA's address key in SAVEKEY. 

Bl Move PROGB's address key to the address key field ($TCBADS) of the TCB. 

Q Add X'34' to the load point address returned by the WHERES instruction. Put 
the results of the addition in PGMBECB. PROGA assumes that PROGB defines an 
ECB immediately after the PROGRAM statement. The PROGRAM statement 
generates 52 bytes (X'34') of code. 

B Post the ECB with a - 1. The operand PI = PGMBECB allows the ECB to be 
calculated by the ADD instruction. 

Q Restore PROGA's address key from SAVEKEY. 

Q Indicate the name of the program to be found. The name of the program is the 
name assigned to it when the program was link edited. 

The following program shows how PROGB receives the POST from PROGA. This 
program must be in storage when PROGA issues the WHERES instruction. 

B PROGB PROGRAM START 

ECBl ECB 

START EQU * 

B WAIT ECBl 



PROGSTOP 

ENDPROG 

END 

B Identify the label at which to start executing (START). 

B Define an event control block (ECB). The program defines the ECB here 
because it will always be 52 bytes (X ' 34 ' ) from the program load point. 

B Wait for PROGA to post the program. 
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Moving Data Across Partitions 



You can also move data across partitions. The following programs show how to 
move data to a program in another partition. The first program, PROGA, finds the 
second program, PROGB, stores its address key, and moves data to the dynamic 
storage area of PROGB. In this example, PROGB must be loaded before PROGA. 








PROGA 


PROGRAM 


START 


□ 


COPY 


PROGEQU 


B 


COPY 


TCBEQU 


START 


EQU 


* 


B 


WHERES 


PROGB, ADDRB, KEY=KEYB 


B 


IF 


(PROGA, EQ,0), THEN 




PRINTEXT 'PROGRAM NOT FOUND* 




GOTO 


DONE 




ENDIF 








READTEXT MSG, '©ENTER UP TO 30 CHARACTERS' ,MODE=LINE 






MOVE 


#2, ADDRB 




MOVE 


PROGBBUF, ($PRGSTG,#2) ,FKEY=KEYB 






TCBGET 


SAVEKEY, $TCBADS 




TCBPUT 


KEYB,$TCBADS 




1 


MOVE 


#2, PROGBBUF 




1 


MOVE 


(0,#2) ,MSG, (30,BYTE) ,TKEY=KEYB 




1 


TCBPUT 


SAVEKEY, $TCBADS 


DONE 


PROGSTOF 




MSG 


TEXT 


LENGTH=30 


PROGBBUF DATA 


F'O' 


[Qj PROGB 


DATA 


C PROGB ' 


SAVEKEY 


DATA 


F'O' 


ADDRB 


DATA 


F'O' 


KEYS 


DATA 
ENDPROG 


F'O' 






END 








Q Copy the PROGRAM equates into the program. 

Q Copy the task control block (TCB) equates into the program. 

01 Find the program defined at PROGB, put the address of the program in 
ADDRB, and put the address key of the program in KEYB. 

01 If the WHERES instruction returns a zero, print an error message and end the 
program. 

Q Prompt the operator for data and place the operator's response in MSG. 

Q Move the address of PROGB in register 2. 

Q Move the address of PROGB's dynamic storage area to PROGBBUF. Indicate 
PROGB's address key (FKEY = KEYB). PROGB has STORAGE = 256 on its 
PROGRAM statement. This operand causes the system to acquire a 256-byi;e area 
of storage when it loads PROGB. The address of this area is in PROGB's program 
header (at SPRGSTG). 

B Save PROGA's address key in SAVEKEY. 
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B Move PROGB's address key to the address key field (STCBADS) of the TCB. 
[Q Move the address of PROGB's dynamic storage area to register 2. 



Move the data that the operator entered (MSG) into PROGB's dynamic 
storage area. Move 30 bytes and indicate the address key of the program to which 
the data is being moved (TKEY = KEYB). 

03 Restore PROGA's address key from SAVEKEY. Note that STCBADS is 
immediately restored to its original value. Doing so avoids unpredictable results. 



Indicate the name of the program to be found. The name of the program is the 
name assigned to it when the program was link edited. 

The following program shows how PROGB receives the data from PROGA. The 
program must be in storage when PROGA issues the WHERES instruction. 



B 



PROGB PROGRAM START, ST0RAGE=256 
START EQU * 



MOVE #1,$ST0RAGE 
MOVE MSG2,(0,#1),(30,BYTE) 
PRINTEXT '@THE DATA THAT WAS PASSED WAS' 
PRINTEXT MSG2 
PROGSTOP 
MSG2 TEXT LENGTH=30 
ENDPROG 
END 



[] Identify the label at which to start executing (START). Specify 256 bytes of 
dynamic storage. (Even though the program requires only 30 bytes, the system 
rounds up to a multiple of 256.) 

B Insert instructions here to wait for PROGA to send data. 

B Move the address of the dynamic storage area (contained in SSTORAGE) to 
register 1. 

B Move 30 bytes from the dynamic storage area to MSG2. 

B Print the data. 

STCBADS is used to calculate the partition and address to/from which data will be 
transferred. 
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Reading Data across Partitions 

You can read data across partitions with the READ instruction. 

In the follovy'ing example, program PROGA reads data and passes it to a buffer in 
program PROGB. PROGA assumes that PROGB is in another partition. 



i 



PROGA PROGRAM START, DS=ACCOUNTS 

COPY PROGEQU 

COPY TCBEQU 

START EQU * 

WHERES PROGB, ADDRB,KEY=KEYB 

IF (PROGA, EQ,0), THEN 
PRINTEXT 'PROGRAM NOT FOUND' ,SKIP=1 
GOTO DONE 

ENDIF 

MOVE #2,ADDRB 

MOVE PROGBBUF , ($PRGSTG , #2) , FKEY=KEYB 

TCBGET SAVEKEY,$TCBADS 
TCBPUT KEYB,$TCBADS 

READ DS1,*,P2=PR0GBBUF 

TCBPUT SAVEKEY,$TCBADS 
DONE PROGSTOP 

SAVEKEY DATA F'O' 

PROGB DATA C PROGB ' 

ADDRB DATA F'O' 

KEYB DATA F'O' 

ENDPROG 

END 

Q Define data set ACCOUNTS on the IPL volume. 

Q Copy the PROGRAM equates into the program. 

Q Copy the task control block (TCB) equates into the program. 

Q Find the load-point address and address key of PROGB. Place the load-point 
address of PROGB into ADDRB and the address key of the program into KEYB. 

Q If the WHERES instruction returns a zero, indicating an error, print an error 
message and end the program. 

Q Move the address key of PROGB into software register 2. 

jQj Move the address of PROGB's dynamic storage area into PROGBBUF in 
PROGA. The STORAGE = operand on the PROGRAM statement of PROGB 
causes the system to acquire a 256-byte storage area when it loads the program. The 
address of this storage area is in PROGB's program header (at $PRGSTG). 

Q Save PROGA's address key in SAVEKEY. 

Q Moves PROGB's address key to the address key field ($TCBADS) of the TCB. 

EO Read one record from the data set ACCOUNTS into PROGBBUF. Because 
PROGBBUF is the label of the P2 = operand on the READ instruction, the system 
uses the contents of PROGBBUF as the location where the data is to be stored. 
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Restore PROGA's address key from SAVEKEY. 

IQ Indicate the name of the program to be found. (The name of the program is 
the name you give the program when you Hnk edit it.) 

The following program shows how PROGB receives the data from PROGA. The 
program must be in storage when PROGA issues the WHERES instruction. 

n PROGB PROGRAM START, ST0RAGE=256 
START EQU * 



MOVE #1,$ST0RA6E 

MOVE OUTPUT, (0,#1), (50, BYTE) 

PRINTEXT '(PTHE DATA RECEIVED FROM PROGA IS :' 

PRINTEXT OUTPUT, SKIP=1 

OUTPUT TEXT LENGTH=50 
ENDPROG 
END 

Q Identify the label at which to start executing (START). Specify 256 bytes of 
dynamic storage. (Even though the program requires only 50 bytes, the system 
rounds up to a multiple of 256.) 

Q Move the address of the dynamic storage area (contained in $STORAGE) to 
software register 1. 



^ Q Move 50 bytes of data from the dynamic storage area into OUTPUT. 

Q Print a message. 
Q Print the data. 
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Chapter 13. Communicating with Other Programs (Virtual 
Terminals) 






A virtual terminal is a logical EDX device that simulates the actions of a physical 
terminal. An EDL application program can acquire control of, or enqueue, a virtual 
terminal just as it would an actual terminal. By using virtual terminals, programs 
can communicate with each other as if they were terminal devices. One program 
(the primary) loads another program (the secondary) and takes on the role of an 
operator entering data at a physical terminal. 

The secondary program can be an application program or a system utility, such as 
SCOPYUTl. You can use virtual terminals, for example, to provide simpUfied 
menus for running system utilities. An operator could load a virtual terminal 
program, select a utility to run, and allow the program to pass predefined 
parameters to the utility. 

Virtual terminals simulate roll screen devices. The terminals communicate through 
EDL terminal I/O instructions contained in the virtual terminal programs. The 
programs use a set of virtual terminal return codes to synchronize communication. 

For example, an EDL program, the primary program, loads a system utility such as 
SCOPYUTl. The program cannot distinguish between connection to a real terminal 
or a virtual terminal. The program uses the READTEXT instruction to read the 
prompts from the utility. Then it uses the PRINTEXT instruction to send replies to 
the utiUty. 



Defining Virtual Terminals 



To define a virtual terminal connection during system generation, you must: 

• Define two TERMINAL configuration statements. 

• Include the supervisor module lOSVIRT. 

For information on how to define TERMINAL statements and include lOSVIRT, 
refer to the Installation and System Generation Guide. 

You can find out if your system has virtual terminals by using the LA command of 
the STERMUTl utihty. If your system has virtual terminals, $TERMUT1 hsts the 
virtual terminals as follows: 



NAME 



ADDR TYPE 



PART HARDCOPY ON-LINE 



CDRVTA ** 

CDRVTB ** 



VIRT 
VIRT 



YES CONNECTED CDRVTB 
YES CONNECTED CDRVTA 



SYNC=YES 



The output from $TERMUT1 indicates that CDRVTA is the primary program 
(SYNC = YES). 
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The DEVICE and ADDRESS parameters of the TERMINAL statement define the 
terminals as virtual terminals. The two TERMINAL statements must reference each 
other, as shown below. 

CDRVTA TERMINAL DEVICE=VIRT,ADDRESS=CDRVTB,SYNC=YES 
CDRVTB TERMINAL DEVICE=VIRT5ADDRESS=CDRVTA 

The SYNC parameter of terminal CDRVTA designates it as the terminal to which 
synchronization events will be posted. The synchronization between virtual 
terminals is discussed in "Interprogram Dialogue." 



Loading from a Virtual Terminai 



When an EDX program is loaded from a real terminal, that terminal becomes its 
"primary" communication port. When one program loads another, the current 
terminal of the first program is "passed" and becomes the primary terminal of the 
second. It is this convention that allows a new program to estabUsh a virtual 
terminal as the primary port for the loaded program. For example: 





ENQT 
LOAD 
ENQT 

• 


SEC 

$TERMUT1 , LOGMSG=NO , EVENT=ENDWAIT 

PRIM 


PRIM 
SEC 


• 

lOCB 
lOCB 


CDRVTA 
CDRVTB 



After this sequence, STERMUTl has CDRVTB (the "other" end of the channel) as 
its primary port, and the loading program has CDRVTA ("this" end of the channel) 
as its current port. 



Interprogram Dialogue 



Once the connection between the two communicating programs has been estabhshed, 
you can use the PRINTEXT, READTEXT, PRINTNUM and GETVALUE 
instructions to send and receive data. You can generate attention interrupts with the 
TERMCTRL instruction. (Refer to the Language Reference for information on the 
TERMCTRL instruction.) The usual conventions with respect to output buffering 
and advance input apply. 

To use virtual terminals, you must know something about communications protocol 
(such as knowing when a program is ready for input or has ended). You can use 
the task code word to find out this information. 



o 



13-2 SC34-0943 



Communicating with Other Programs (Virtual Terminals) 



Sample Program 



The following sample program uses virtual terminals to process the prompt/reply 
sequence of the $INITDSK utility. The program initiaUzes volume EDX003. 



The replies to SINITDSK prompts begin at label REPLIES + 2. (The six bytes in 
each TEXT statement is preceded by two length/count bytes.) 

Each reply is 8 bytes long (six bytes of text plus two length/count bytes). The 
program issues a READTEXT until SINITDSK prompts for input. Then the 
program issues a PRINTEXT to send the reply to the SINITDSK prompt. After 
SINITDSK ends, the program prints a completion message to the terminal. 






INIT 


PROGRAM 


BEGIN 




A 


lOCB 


CDRVTA 


SYNC TERMINAL 


B 


lOCB 


CDRVTB 




DEND 


ECB 






BEGIN 


EQU 


* 






ENQT 


B 






LOAD 


SINITDSK, LOGMSG=NO,EVENT=DEND 




ENQT 


A 


GET SYNC TERMINAL 




MOVEA 


#l,REPLIES+2 






DO 


6, TIMES 


REPLY TO PROMPTS 




DO 


UNTIL, (RETCODE, EQ, 8) BREAK CODE 




READTEXT LINE,MODE=LINE 


LOOP FOR PROMPT MSGS 




MOVE 


RETCODE, INIT 


SAVE RETURN CODE 




ENDDO 








PRINTEXT 


(0,#1) 


SEND REPLY 




ADD 


#1,8 


NEXT REPLY 




ENDDO 








READTEXT 


LINE,MODE=LINE 


PGM END MSG 




WAIT 


DEND 


WAIT FOR END EVENT 




DEQT 








PRINTEXT 


'EDX003 INITIALIZED 


1 




PROGSTOP 






RETCODE 


DATA 


F'O' 


RETURN CODE 


LINE 


TEXT 


LENGTH=80 




REPLIES 


EQU 


* 






TEXT 


'IV 


COMMAND? 




TEXT 


' EDX0O3 ■ 


VOLUME? 




TEXT 


'Y 


CONTINUE? 




TEXT 


'60 


NBR OF DATA SETS? 




TEXT 


'N 


VERIFY? 




TEXT 


'EN 


COMMAND? 




ENDPROG 








END 
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Chapter 14. Designing and Coding Sensor I/O Programs 

This chapter provides the information you need to code a sensor I/O application 
program. Topics covered include: 

• Sensor I/O devices 

• Symbolic I/O assignments 

• Sensor I/O instructions. 

The chapter also provides several examples. 



What is Digital Input/Output? 



c 



A unit of digital sensor I/O is a physical group of sixteen contiguous points. The 
entire group of sixteen points is accessed as a unit on the I/O instruction level. 
Programming support allows logical access down to the single point level. 

Digital input (DI) is usually used to acquire information from instruments which 
present binary encoded output or to monitor contact/switch status (open/closed). 
Digital output (DO) is used to control electrically-operated devices through closing 
relay contacts, such as pulsing stepping motors. 

Process interrupt (PI) is a special form of digital input. If a point of digital input 
changes state, and then changes state again, without an intervening READ operation 
from the program, the status change will be undetected. With process interrupt, a 
point changing from the off state to on generates a hardware interrupt that is then 
routed through software support to an interrupt-servicing application program that 
can respond to the external event that caused the interrupt. Process interrupt is 
often used for monitoring critical or alarm conditions that must be serviced quickly, 
the occurrence of which must not go undetected. 



What is Analog Input/Output? 



A physical unit of analog input (AI) can be a group of eight points or sixteen points, 
depending on the type. Analog output (AO) is installed in groups of two points. 
Each point of analog input or analog output is accessed separately. 

Analog input is used to monitor devices that produce output voltages proportional 
to the physical variable or process being measured. Examples include laboratory 
instruments, strain gauges, temperature sensors, or other nondigitizing instruments. 
Digital input was described as monitoring an on/off status; only two conditions were 
possible. With analog input, the information is carried in the ampUtude of the 
voltage sensed rather than in its presence or absence. 

The starter supervisor contains no support for sensor I/O. You must perform a 
tailored system generation to include the required support modules in your own 
supervisor. 
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Figure 14-1 shows how sensor devices are connected to a Series/1 through the 4982 
sensor I/O unit. The devices (DI, DO, PI, AO, and AI) attach to a controller, which 
in turn attaches to the Series/ 1. The sensor I/O attachment (controller), and each of 
the devices attaching to it, have unique hardware addresses. In this figure, the 
physical connections are there, and the hardware addresses are assigned (wired in), 
but the starter supervisor in storage lacks the support necessary to operate the 
devices. 



J 



Series/1 



Supervisor 
with 

sensor I/O 
support 



Sensor I/O 
attachment 



Address 68 




Digital output 
group address 70 



Digital output 
group address 71 



Digital input 
group address 72 



\. 



j^ 



BG1143 



Figure 14-1. Sensor Device Connections 



Building a tailored supervisor involves the assembly of a series of system 
configuration statements that reflect the I/O configuration you wish to support. For 
more information on system configuration statements, refer to the Installation and 
System Generation Guide. When programs reference these devices, they use symbohc 
references, rather than actual addresses. The I/O definition statement (lODEF) 
estabhshes the logical link between the addresses defined in the supervisor, and the 
symbols used to read from and write to the devices at those addresses from an 
apphcation program. 

All sensor-based input/output operations are performed by executing a sensor-based 
I/O (SBIO) instruction. The type of operation is determined by the type of device 
referenced in the instruction. For more information on the SBIO statement, refer to 
the Language Reference. The symbohc reference to a logical device in the SBIO 
statement is linked to the definition in the lODEF statement, which relates that 
device to the hardware address specified by the system configuration statement at 
system generation time. 
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What are Sensor-Based I/O Assignments? 



The sensor-based I/O instruction (SBIO) refers to the I/O devices using a 3-or 
4-character name. The first two characters identify the type of device: AI, DI, PI, 
AO, and DO for analog input, digital input, process interrupt, analog output, and 
digital output, respectively. The next one or two characters are the identification for 
the device, a number between 1 and 99. For example, if you have three analog input 
terminals, you may identify them as All, AI2, and AI3. Before the application 
program is compiled, the sensor-based I/O definition statement (lODEF) assigns the 
actual physical addresses. All SBIO instructions are independent of the physical 
location of the sensor I/O points. 



The assignment of sensor I/O symboHc addresses is described under "Providing 
Addressability (lODEF)" on page 14-4. Figure 14-2 shows the relationship between 
sensor-based I/O instructions, definition statements, and configuration statements. 



Sensor-based 
I/O execution 
instruction 
(SBIO) 



Sensor-based 
I/O definition 
instruction 
(lODEF) 



CC can be: 


Specifies 


AI 


logical 


AO 


device 


DI 




DO 




X can be: 




1-99 





Sensor- based 
configuration 
statement 
(SENSORIO) 



CCx 

Specifies 
the action 




CCx 

Specifies 
the physical 
location 




Describes 
the physical 
device 







Figure 14-2. Sensor-Based Symbolic I/O Assignment 



Coding Sensor-Based instructions 



This section describes the instructions used in sensor-based I/O appHcations. The 
following instructions are defined: 

• lODEF - provides addressability by specifying physical location 

• SBIO - specifies the I/O operation to be performed 

• SPBCPIRT - allows control to be returned to the supervisor from a special 
process-interrupt routine. 
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Providing Addressability (lODEF) 

Use the lODEF instruction to provide addressability for the sensor-based I/O 
facihties which are referenced symbolically in an application program. The specific 
form used varies with the type of I/O being performed. 

Group all lODEF statements of the same form (AI, AO, DI, DO, or PI) together in 
the program and place them ahead of the SBIO instructions that reference them. 

All lODEF statements must be in the same assembly module as the TASK or 
ENDPROG statement. For high level languages, see the appropriate manual for 
instructions on how to accomplish this. If the SBIO instructions are to be in a 
separate module, you can provide addressabiUty using ENTRY/EXTRN statements. 

Each lODEF statement creates an SBIOCB control block. The contents of the 
SBIOCB is described in the Internal Design. 

The lODEF statement generates a location into/from which data is read/written. 
You must create a separate lODEF for each task; different tasks cannot use the 
same lODEF statement. 



Examples 



Refer to the Language Reference for the syntax of PI, DO, DI AO, and AI. 



The following lODEF instructions define two process interrupts, a digital output 
group, a digital output group as external sync, a digital input group, an analog input 
point, and an analog output point. 

lODEF PI1,ADDRESS=48,BIT=2 

lODEF PI2,ADDRESS=49,BIT=15 

lODEF D01,TYPE=GR0UP,ADDRESS=4B 

lODEF D02,TYPE=EXTSYNC,ADDRESS=4A 

lODEF DI1,TYPE=GR0UP,ADDRESS=49 

lODEF AI 1 , ADDRESS=72 , P0INT=1 , RAN6E=50MV , ZCOR=YES 

lODEF A02,ADDRESS=75,P0INT=1 

The SBIO instruction references the digital and analog I/O points as described under 
the SBIO instruction. Process interrupts are referenced by the POST and WAIT 
instructions and are described under the respective instruction. Further examples of 
lODEF statements are shown following the SBIO instruction. 
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SPECPI - Process Interrupt User Routine 

The SPECPI option of the lODEF statement defines a special process interrupt 
routine. The supervisor executes a routine written in Series/ 1 assembler language 
when the defined interrupt occurs. The purpose is to provide the minimum delay 
before service of the interrupt, by bypassing the normal supervisor interrupt 
servicing. Multiple special process-interrupt routines are allowed in a program. 

TYPE = BIT The system gives control to the specified routine when an 

interrupt occurs on the specified bit. On return to the supervisor, 
the contents of register 1 (Rl) must be the same at entry to the 
user's routine and RO must contain either "0" or a POST code. 
In the latter case, R3 must contain the address of an ECB to be 
posted by the POST instruction. R7 contains the supervisor 
return address upon entry. If the user routine is in partition 1, 
you can return to the supervisor with the BXS (R7) instruction. 
Otherwise, you must return with the SPECPIRT instruction. 
You can use SPECPIRT in partition 1 . The value that is in R7 
upon entry may be used to return to the supervisor using BXS 
(R7) only if the user routine is in partition 1. 

TYPE = GROUP The system gives control to the specified routine you provide if 
an interrupt occurs on any bit in the PI g|"oup. The PI group is 
not read or reset; reading or resetting the PI group is the 
responsibility of your routine. Control returns to the supervisor 
with a branch to the entry point SUPEXIT. You must include 
the module SEDXATSR with your program to use SUPEXIT. If 
the routine processes the interrupt on level 0, it can issue a 
Series/ 1 hardware exit level instruction (LEX) instead of 
returning to SUPEXIT. Issuing the LEX instruction greatly 
improves performance. 

Note: To use TYPE = GROUP, you must be familiar with the operation of the 
Series/ 1 process interrupt feature. Your routine must contain all instructions 
necessary to read and reset the process-interrupt group to which it refers. 
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Using the Special Process-Interrupt Bit 



lODEF PI2,ADDRESS=48,BIT=3,TYPE=BIT,SPECPI=FASTPI1 
FASTPIl EQU * 
D MVW R1,SAVER1 



MVA PI2,R3 
MVWI 3,R0 
MVW SAVER1,R1 
SPECPIRT 



D Save Rl. 

Qj Put the address of PI2 in R3. 

Q Posting code in RO. 

Q Restore Rl. 

Q Return to supervisor. 

In the following example, control is given to the user at label FASTPI2. \^ 

lODEF PI6,ADDRESS=49,TYPE=GR0UP,SPECPI=FASTPI2 

FASTPI2 EQU * 



gr-^ 
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Specifying 1/0 Operations (SBIO) 

The SBIO instruction provides communication using analog and digital I/O. 
Options allow you to: 

• Index using a previously defined BUFFER statement. 

• Update a buffer address in the SBIO instruction after each operation. 

• Use a short form of the instruction, omitting loc (data location) to imply a data 
address within the SBIOCB. 

Options available with digital input and output provide PULSE output and the 
manipulation of portions of a group with the BITS = (u,v) keyword parameter. 

SBIO instructions are independent of hardware addresses. The actual operation 
performed is determined by the definition of the sensor address in the referenced 
lODEF statement. 

The lODEF statement generates a location into/from which data is read/written. 
You must create a separate lODEF for each task; different tasks cannot use the 
same lODEF statement. 

A sensor based input/output control block (SBIOCB) is inserted into an appUcation 
program for each referenced sensor I/O device. The SBIOCB, containing a data I/O 
area and an event control block (ECB), supplies information to the supervisor. 
When an SBIO instruction executes, the supervisor either stores data (for AI and DI 
operations) or fetches data (for AO and DO operations) from a location in the lOCB 
with the label of the referenced I/O point (for example, All, DI2, D033, AOl). An 
application program can reference these locations the same way any other variable is 
referenced, allowing you to use the short form of the SBIO instruction (for example, 
SBIO DIl), and subsequently reference DIl in other instructions. You can equate a 
more descriptive label to the symboHc names (for example SWITCH EQU DIl 5), 
but the SBIO instruction must use the symbolic name as described above. 

Each control block also contains an ECB to be used by those operations which 
require the supervisor to service an interrupt and "post" an operation complete. 
These include analog input (AI), process interrupt (PI), and digital I/O with external 
sync (DI/DO). For process interrupt, the label on the ECB is the same as the 
symbohc I/O point (for example PIx). For analog and digital I/O, the label is the 
same as the symboHc I/O point with the suffix "END" (for example DIxEND). 
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Reading Analog Input (example) 

This example shows SBIO instructions and lODEF statements to read analog input. 

TASK PROGRAM GO 

lODEF AI1,ADDRESS=72,P0INT=5 

SBIO All 

SBIO All, DAT 

SBIO All, BUF, INDEX 

SBIO All, (BUF, #1) 

SBIO AI1,BUF,2,SEQ=YES 

SBIO All, BUF, 2 
or 

B SBIO AI1,BUF,2,SEQ=N0 

Q Data into location All. 

Q Data into location DAT. 

B All into next location of BUF. 

D All into location (BUF, #1). 

B Read 2 sequential AI points into next 2 locations of BUF. 

B Read the same point 2 times and put information in 2. 

B Locations of BUF. 

Writing Analog Output (example) 

This example shows SBIO instructions and lODEF statements to write analog 
output. 

_ lODEF A01,ADDRESS=63 

SBIO AOl 

SBIO AOl, DATA 

SBIO AOl, 1000 

SBIO AO1,(0,#1) 

SBIO AOl, BUF, INDEX 

B Set AOl to value in AOl. 

B Set AOl to value in DATA. 

B Set AOl to 1000 

B Set AOl to value in (0,#1) 

B Set AOl to value in next location of BUF. 



> 






V 
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Reading Digital Input (example) 

This example shows SBIO instructions and lODEF statements to read digital input. 

lODEF DI1,TYPE=GR0UP,ADDRESS=49 

lODEF DI2JYPE=SUBGR0UP,ADDRESS=48,BITS=(7,3) 

lODEF DI3,TYPE=EXTSYNC,ADDRESS=62 

SBIO DIl 

SBIO DIl, DATA 

SBIO DI1,(0,#1) 

SBIO DIl, BUF, INDEX 

SBIO DI1,BDAT,BITS=(3,5) 

SBIO DI2 

SBIO DI2,DAT2 

SBIO DI2,D,BITS=(0,3) 

SBIO DI2,E,BITS=(0,1) 

SBIO DI2,F,BITS=(2,1),LSB=7 

SBIO DI3,G,128 



^ktoiX 



I 



Q Data into location DIl. 

B DIl into location DATA. 

B DIl into location (0,#1). 

DIl into next location of BUF. 

B Bits 3 to 7 of DIl into BDAT. 

B Bits 7 to 9 of D12 into D12. 

B Bits 7 to 9 of D 12 into DAT2. 

B Bits 7 to 9 of D12 into D. 

B Bit 7 ofD12intoE. 

ICT Bit 9 of D 12 into location F bit 7. 

Read 128 words into G using external sync. 



Writing Digital Output (example) 

This example shows SBIO instructions and lODEF statements to write digital 
output. 

lODEF D03,TYPE=GR0UP,ADDRESS=4B 

lODEF D012,TYPE=SUBGR0UP,ADDRESS=4A,BITS=(5,4) 

lODEF D013,TYPE=EXTSYNC,ADDRESS=4F 

SBIO D03 

SBIO D03,D0DATA 

SBIO 003,1023 

SBIO D03,(DATA,#1) 

SBIO D03,7,BITS=(3,3) 

SBIO D012,15 

SBIO D012,X,BITS=(0,4) 

SBIO D012,1,BITS=(0,1) 

SBIO DO13,Y,80 
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B Value of location DOS to D03. 

B Value of DODATA to D03. 

B Set DOS to 102S. 

B Value at (DATAJl) to DOS. 

B Set bits S to 5 of DOS to 7. 

B Set bits 5 to 8 of D012 to 15. 

B Set bits 5 to 8 of DO 12 to value in X. 

B Set bit 5 of DO 12 to 1. 

B Write 80 locations of "Y" to DO IS external sync. 

Pulse Digital Output (example) 

This example shows pulse digital output. 

lODEF D013,TYPE=SUBGR0UP,BITS=(3,1) 
lODEF D014,TYPE=SUBGR0UP,BITS=(7,4) 

BSBIO D013, (PULSE, UP) 
SBIO D014, (PULSE, DOWN) 

B Pulse DO 13 bit 3 to on and then off. /""^ 

B Pulse DO 14 bits 7 to 10 off and then on. 

Returning from the Process-interrupt Routine (SPECPIRT) 

Use the SPECPIRT instruction to return control to the supervisor from a special 
process interrupt (SPECPI) routine. If the user routine is in partition 1, a branch 
instruction is used to return. Return from another partition requires execution of a 
Series/I assembler SELB instruction after registers RO and RS are saved in the level 
block to be selected. SPECPIRT is used only for TYPE = BIT SPECPI routines. 
See the description of lODEF (SPECPI) for additional information. 

label SPECPIRT 

Required: none 
Defaults: none 
Indexable: none 



o 
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Analog Input Sample 

This program takes 256 samples from analog input address All at a sampling rate of 
10 points/second. Set the run light on in the lab at the start of the run and turn it 
off at the end. The run light is connected to bit 3 of group D02. 

TKNAME 



START 



PROGRAM 


START 


lODEF 


D02JYPE=GR0UP,ADDRESS=87 


lODEF 


AI1,ADDRESS=83 


SBIO 


D02,1,BITS=(3,1) 


DO 


256, TIMES 


STIMER 


100 


SBIO 


All, BUFR, INDEX 




WAIT TIMER 


ENDDO 




SBIO 


D02,0,BITS=(3,1) 



BUFR 



BUFFER 



256 






Q Turn on run light. 

Q Set up for 256 points. 

B Set timer for 100 MS. 

Q Read All with automatic indexing into the buffer BUFR. and then wait for the 
timer to expire. 

Q End of loop. 

01 Turn off run light. 

B 256 word buffer. 



The program begins by writing a 1 into bit 3 of digital output group D02. A DO 
loop initializes for 256 cycles. At this point, a software timer is set up for 100 
milliseconds to provide sampling at 10 points/second. The analog data is read into 
BUFR using the SBIO instruction with automatic indexing. After the data is read, 
the program waits for the timer to expire before returning for the next sample. 
When all the data is collected, the run light is turned off by writing a into bit 3 of 
D02. 
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Analog Input With Buffering To Disk 

This program takes analog data readings at equal time intervals. The number of 
data points and the time interval in milliseconds are read in from the operator's 
terminal. The program will allow from 10 to 10,000 data points to be taken at time 
intervals between 10 milliseconds and 10 seconds (10,000 msec). The data collection 
is initiated by a process interrupt start signal. The program is ended by using the 
keyboard function "AB." Also, a second keyboard function, "NP," is used to print 
a status switch. The switch will be equal to zero if the start signal has not been 
received or equal to the number of data points to be read if the start signal has been 
received and data collection has begun. 





READATA 


PROGRAM 


BEGIN, DS=?? 






ATTNLIST 


(AB, ABORT, NP, SWPRNT) 


D 


ABORT 


MOVE 
ENDATTN 


SWITCH,! 




SWPRNT 


PRINTEXT 


TXT10 


B 




PRINTNUM 


SWITCH 






PRINTEXT 


SKIP=1 






ENDATTN 








lODEF 


AI1,ADDRESS=91,POINT=0 






lODEF 


PI1,ADDRESS=94,BIT=15 


* 




EXPERIMENT INITIALIZATION 




BEGIN 


PRINTEXT 


TXTl 


B 




GETVALUE 


RUNUM,TXT2 


D 


GETINT 


GETVALUE 


INTVL,TXT3 






IF 


(INTVL,LT, 10), OR, (INTVL,GT,1G000), GOTO, GETINT 


m 


GETPTS 


GETVALUE 


NPTS,TXT4 






IF 


(NPTS,LT, 10), OR, (NPTS,GT, 10000), GOTO, GETPTS 


n 




WRITE 


DS1,RUNUM 






RESET 


SWITCH 






Q End the experiment. 

01 Print experiment switch. 

Q Request run identifier. 

Q Request time interval. 

H Request number of points. 

01 Run parameters in first sector. 
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1 



PRINTEXT TXT9 

WAIT PIl, RESET 

MOVE SWITCH, NPTS 

DO NPTS 

STIMER INTVL 

SBIO All, BUFFER, INDEX 

IF (BUFINDEX,EQ, 128), GOTO, ATTACH 

IF (BUFINDEX,NE,256),60T&,TWAIT 

MOVE BUFINDEX,0 

ADD P0INTCNT,256 
ATTACH IF (DISK, NE,-1), GOTO, STOP 

ATTACH DISKTASK 
TWAIT WAIT TIMER 

IF (SWITCH, EQ,1), GOTO, STOP 
ENDLOOP ENDDO 

IF (BUFINDEX,EQ,0) ,0R, (BUFINDEX,EQ,128) , GOTO, STOP 

WAIT DSl 

ADD POINTCNT,BUFINDEX 

ATTACH DISKTASK 
STOP WAIT DSl 

ENQT 

PRINTEXT TXT6 

PRINTNUM POINTCNT 

PRINTEXT TXT7 

DEQT 

PROGSTOP 



Q Print ready message. 
Q Wait for start signal. 
B Set switch to NPTS. 



Q Begin the data acquisition portion of the program. Perform the loop the 
number of times set in step 3. 



Time interval set above. 
IQ Read a data point. 

First buffer full? 
Q No, is second full? 

Yes, reset buffer index. 
03 Increment data counter. 

Is disk task attached? 
3 Start the disk output task. 
IQ Wait for end of time interval. 
B51 Test for "end." 
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Wait for disk write. 
^3 Update data counter. 
^3 Start last disk output. 
03 Wait for last output operation. 
Qj Get control of terminal. 
1^ Print terminating message. 

Release terminal. 



The following is the data recording task. It is attached by the data acquisition task 
each time that 128 words of data have been read. One portion of the buffer will be 
transferred to disk while data is being read into the other portion of the buffer. The 
task runs on level 3 at a lower priority than the data acquisition task in order to 
maximize timing accuracy. 





DISKTASK TASK 


DISKl, 300, EVENT=DISK 




DISKl 


WRITE 


DS1,BUFFER1,ERR0R=DISKERR 


□ 




DETACH -1 






WRITE 


DS1,BUFFER2,ERR0R=DISKERR 


B 




DETACH -1 






GOTO 


DISKl 


i 


DISKERR 


MOVE 
ENQT 


ERROR, DISKTASK 






PRINTEXT TXT5 


B 




PRINTNUM ERROR 
PRINTEXT SKIP=1 


P 




DEQT 




B 




ENDTASK 1 




TXTl 


TEXT 


'^SAMPLE ANALOG DATA ACQUISITION PROGRAMg' 




TXT2 


TEXT 


'CENTER RUN NUMBER ' 




TXT3 


TEXT 


'CENTER INTERVAL IN MS (10-10000) ' 




TXT4 


TEXT 


'©ENTER NO. OF POINTS (10-10000) ' 




TXT5 


TEXT 


'laDISK ERROR ' 




TXT6 


TEXT 


■(3RUN ENDED AFTER ' 




TXT7 


TEXT 


' POINTS©' 




TXT9 


TEXT 


'©READY FOR PI SIGNAL TO BEGIN TAKING DATA© 




TXTIO 


TEXT 


'©EXPERIMENT SWITCH = ' 



\y 



Q Successful completion. 

Q Successful completion. 

01 Save error code. 

Q Get control of terminal. 

Bl Print disk error message. 

B Release terminal. 

H Detach with code = 1 . 



o 
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{ 



I 



POINTCNT 


DATA 


F'O" 


SWITCH 


DATA 


F'O' 


RUNUM 


DATA 


F'O' 


INTVL 


DATA 


F'O' 


NPTS 


DATA 


F'O' 


ERROR 


DATA 


F'O' 


BUFFER 


BUFFER 


256,INDEX=BUFINDEX 


BUFFERl 


EQU 


BUFFER 


BUFFER2 


EQU 


BUFFER+256 




ENDPR06 




END 








Q Number of points taken. 

B Set to "1" for "end." 

Q Run identifier. 

Q Time interval. 

Q Number of points to take. 

Q Data buffers. 

B First 128 words. 

B Second 128 words. 

Digital Input and Averaging 

This example illustrates the programming of a simple time-averaging appHcation. 
The program reads digital input group DIl every time a process interrupt occurs on 
PI2. One complete scan is 128 data points. Each scan is added to a 
double-precision averaging buffer. The number of scans is read from the terminal as 
an initialization parameter. Also, the program asks whether to reset the averaging 
buffer before starting to scan. The maximum number of scans must be less than 
1000. 
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START 



BEGIN 



lol 



GETVALUE 


NSCANJXTl 


IF 


(NSCAN,GE,1000) , GOTO, ERROR 


RESET 


PI2 


QUESTION 


TXT2,N0=BEGIN 


MOVE 


ABUFR, 0,256 


DO 


NSCAN 


DO 


128 


WAIT 


PI2 


RESET 


PI2 


SBIO 


DI1,BUFR, INDEX 


ENDDO 




ADDV 


ABUFR, BUFR, 128, PREC=D 


MOVE 


1,0 


ENDDO 




PRINTEXT 


TXT3 






ERROR PRINTEXT 

GOTO 

TXTl TEXT 

TXT2 TEXT 

TXT3 TEXT 

NSCAN DATA 

BUFR BUFFER 

ABUFR BUFFER 

TXT4 TEXT 



TXT4 

START 

'^NUMBER OF SCANS - ' 

' RESET AVERAGING BUFFER? ' 

' ALL SCANS COMPLETED' 

F'O' 

128,INDEX=I 

256 

' TOO MANY SCANS - RE-ENTER@' 



Q Get number of scans. 
S Reset average buffer? 
Q Yes, reset it. 
Q Set up for NSCANS. 
Q Set up for 128 points. 
Q Wait for interrupt. 
Q Reset interrupt. 
H Read DIl (Indexing). 

Q One scan is complete. Move the data to the averaging buffer. 
O Reset buffer index. 
Return for input. 



^itij^ 
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In this example, the number of scans to be done is read from the terminal and 
checked against 1000. If it is greater than or equal, an error message is printed and 
the program returns for a new input parameter. The operator is asked if the 
averaging buffer is to be reset. If yes, the MOVE instruction sets the averaging 
buffer (ABUFR) to 0. A loop is initialized for the number of scans desired. A 
second loop is set up for a single scan of 128 points. The program waits for an 
interrupt on PI2 and, when it occurs, resets the interrupt for the next point, reads the 
digital input DIl using automatic indexing into the buffer BUFR. When a scan is 
complete, the data is added to the ABUFR buffer. The buffer index, I, is reset to 0. 
When all scans are complete, a message is printed. The output from the program is 
illustrated in the following example: 

NUMBER OF SCANS - 33 
RESET AVERAGING BUFFER? Y 
ALL SCANS COMPLETE 
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Chapter 15. Designing and Coding Graphic Programs 

The Event Driven Executive provides various graphics.-oriented tools that can assist 
you in the development of a graphics application. 

The graphics tools you can use are the EDL graphics instructions and the graphics 
utilities. This section describes the graphic instructions supported by the Event 
Driven Executive. The graphic utilities are described in the Operator Commands and 
Utilities Reference. 
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Seven graphics instructions are provided by the Event Driven Executive. These 
graphics instructions, used with the terminal support described, can aid in the 
preparation of graphic messages, allow interactive input, and draw curves on a 
display terminal. 

These instructions are only valid for ASCII terminals that have a point-to-point 
vector graphics capabiHty and are compatible with the coordinate conversion 
algorithm described in the Internal Design for graphics mode control characters. The 
function of the various ASCII control characters used by a terminal are described in 
the appropriate device manual. Such terminals can be connected to the Series/ 1 
through the #7850 Teletypewriter Adapter. 

You use the graphics instructions in the same manner as other Event Driven 
Language instructions, except that the supporting code is included in your program 
rather than in the supervisor. If you code all the instructions in a program, this code 
requires approximately 1500 bytes of storage. 

When using the graphics instructions described, detailed manipulation of terminal 
instructions and text messages is not required. 

All graphics instructions deal with ASCII data. Therefore, when you send an ASCII 
text string to the terminal, code the XLATE = NO parameter on the PRINTEXT 
instruction. 

Use of the graphics instructions requires that your object program be processed by 
the hnkage editor, SEDXLINK, to include the graphics functions which are supplied 
as object modules. See Chapter 5, "Preparing an Object Module for Execution" for 
the description of the autocall option of $EDXLINK, and for information on the 
use of the "AUTO = $AUTO, ASMLIB" option of SEDXLINK. 

The following is a hst of the graphics instructions provided by the Event Driven 
Executive. These instructions are described in detail in the Language Reference. 

• The CONCAT statement concatenates two text strings or a text string and a 
graphic control character. 

• The GIN instruction allows you to specify unsealed coordinates interactively, 
rings the bell, displays cross hairs, waits for the operator to position the cross 
hairs and key in any single character, returns the coordinates of the cross-hair 
cursor, and optionally returns the character entered by the user. 
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The PLOTGIN instruction allows you to specify scaled coordinates, rings the 
bell, displays the cross hairs, and waits for the operator to position the cross 
hairs and key any character. 

The SCREEN instruction converts x and y numbers representing a point on the 
screen of a terminal to the 4-character text string that will be interpreted by the 
terminal as the graphic address of the point. 

The XYPLOT instruction is used to draw a curve on the display connecting 
points specified by arrays of x and y values. 

The YTPLOT instruction draws a curve on the display connecting points equally 
spaced horizontally and having heights specified by an array of y values. Data 
values are scaled to screen addresses according to the plot control block, and 
points outside the range are placed on the boundary of the plot area. 



The Plot Control Block 



The plot control block is required by the PLOTGIN, XYPLOT, and YTPLOT 
instructions. 

The plot control block is 8 words of data defined by DATA statements which 
provide definition of size and position of the plot area on the screen and the data 
values associated with the edges of the plot area. Indirectly, the scale of the plot is 
specified. The format of a plot control block is: 

label 



DATA 


F'xls' 


DATA 


F'xrs' 


DATA 


F'xlv' 


DATA 


F'xrv' 


DATA 


F'ybs' 


DATA 


F'yts' 


DATA 


F'ybv' 


DATA 


F'ytv' 






All 8 explicit values (no addresses) are required and have the following meaning: 

xls X screen location at left edge of plot area 

xrs X screen location at right edge of plot area 

xlv X data value plotted at left edge of plot 

xrv X data value plotted at right edge of plot 

ybs y screen location at bottom edge of plot 

yts y screen location at top edge of plot 

ybv y data value plotted at bottom edge of plot 

ytv y data value plotted at top edge of plot. 
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Example 



In the following example, the graphic control characters (GS, US, ESC, an so on) 
are assumed to have certain meanings for the terminal. A different terminal may 
require the use of different control characters to perform a similar function. 

The example shows the use of the graphics instructions described on the preceding 
pages. This program: 

• Prints a message 

• Plots a curve with axes 

• Puts the cross hairs on the screen 

• Waits for the user to position the cross hairs press a key and carriage return 

• Displays the character entered and x,y coordinates of the cross-hair position. 

You can then end the program or start it again. 



GTEST 


PROGRAM 


START 


START 


EQU 


* 


D 


PRINTEXT 


'GRAPHICS TEST PROGRAM PRESS ENTER @ 




READTEXT 


TEXTl 




CONCAT 


TEXTl, ESC, RESET 


CONCAT 


TEXTl, FF 


PRINTEXT 


TEXTl, XLATE=NO 


STIMER 


1000, WAIT 


CONCAT 


TEXTl, GS, RESET 


SCREEN 


TEXTl, 520, 300, CONCAT=YES 


CONCAT 


TEXTl, US 


PRINTEXT 


TEXTl, XLATE=NO 




PRINTEXT 


TEXTS 


ICT 


YTPLOT 


YDATA, XI, PCB,NPTS,1 


D 


XYPLOT 


YAXISX,YAXISY,PCB,TWO 




XYPLOT 


XAXISX,XAXISY,PCB,TWO 


E9 


PLOTGIN 


X,Y,CHAR,PCB 


B 


PRINTEXT 


TEXT4 




PRINTEXT 


CHAR,XLATE=NO 




PRINTEXT 


TEXT5 




PRINTNUM 


X,2 


ED 


QUESTION 
PROGSTOP 


TEXT6,N0=START 


TEXTl 


TEXT 


LENGTH=30 


TEXT3 


TEXT 


'X-AXIS LABEL' 


TEXT4 


TEXT 


'©CHARACTER STRUCK WAS ' 


TEXTS 


TEXT 


'@X,Y COORDINATES =' 


TEXT6 


TEXT 


'@END PROG (Y/N)? ' 




DAT/i 


X'O201' 


CHAR 


DATA 


F'O' 


YDATA 


DATA 


F'O' 




DATA 


FT 




DATA 


F'O' 




DATA 


F'2' 




DATA 


F'O' 




DATA 


F'l' 




DATA 


F'-2' 




DATA 


F'-l' 
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XI 


DATA 


F'O' 


NPTS 


DATA 


F'8' 


YAXISX 


DATA 


2F'0' 


YAXISY 


DATA 


F'-5' 




DATA 


F'5' 


XAXISX 


DATA 


F'O' 




DATA 


F'lO' 


XAXISY 


DATA 


2F'0' 


TWO 


DATA 


F'2' 


PCB 


DATA 


F'500' 




DATA 


F'lOOO 




DATA 


F'O' 




DATA 


F'lO' 




DATA 


F'lOO' 




DATA 


F'600' 




DATA 


F'-5' 




DATA 


F'5' 


X 


DATA 


F'O' 


Y 


DATA 

ENDPROG 

END 


F'O' 



D Print the message "GRAPHICS TEST PROGRAM PRESS ENTER." 

01 Reset the text string character count and put the ESC code into TEXTl. 

B Put the FF character into TEXTl. 

Q Erase the screen and send the alpha cursor to the home position (upper left 
corner). 

Q Delay for a second to allow the erase sequence to complete. 

Q Reset the text string again and insert the graph mode character (GS) to the text 
string. 

B Form the 4 characters required to draw a dark vector to the screen address 
(520,300). The 4 characters represent the Hi Y, Lo Y, Hi X, and Lo X values. 

B Write an axis label at this position by returning to alpha mode (US). 

B Perform the full operation. Prevent conversion of data (XLATE = NO), as it is 
already in ASCII. 

^1 Plot the data, YD ATA (8 points). The plot area and coordinates are given by 
the 8 words at the label PCB. The plot area in screen addresses is 500 to 1000 in the 
x-direction (horizontal) and 100 to 600 in the y-direction (vertical). The 
corresponding plot area in the user's coordinates is to 10 in the x-direction and -5 
to 5 in the y-direction. 



Draw the X and Y axes with this and the next instruction. Each of these is 
simply a 2-point plot, from the origin to the end point. 
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Put the cross-hair cursor on the screen. The operator should position the 
cursor and enter a character. When the program receives the character, it converts 
the cursor position to the plot coordinates as specified at PCB, and stores the results 
at X and Y. 



Print the results. 

Ask if the operator wishes to end the program. 







BG1145 



Figure 15-1. Graphics Program Output. This figure shows the result of the preceding 
program. 
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f^ Chapter 16. Controlling Spooling from a Program 



What Is Spooling? 

Spooling is the process of writing to disk or diskette an output listing that you 
eventually want to print or display. 

You might use spoohng for any of the following reasons: 

• Your program writes more than one output listing to the same printer. 

• You want a program to finish processing more quickly. (Most programs can 
generate output faster than the printer can print it.) 

• You want to delay printing an output listing until some time after a program has 
executed. 

• You want more than one copy of an output listing. 

• Two or more programs write output listings to the same printer at the same 
time. 






Spooling the Output of a Program 

An application program can control the printing and handling of its spooled output 
with a spool-control record. 

The Spool-Control Record 

The spool-control record consists of a special print record. It must be the first item 
printed by the program after you enqueue the device. 

The spool-control record allows the application program to specify: 

• Whether or not the spool job should be held and not printed 

• Whether or not the spool job should be kept after printing 

• The type of forms to be used to print the output 

• The number of copies to be printed 

• The separator page heading to be printed 

• Whether forms alignment should be done. 

The spool-control record applies only to the spool job that follows it. Therefore, if a 
program creates more than one spool job, and is to control the printing and 
handling of each spool job, each spool job must have its own spool-control record. 

Note: The $S ALT operator command overrides the spool-control record. 
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The format of the spool-control record is as follows: 
Position Contents 

1-8 ***SPOOL 

9 blank 

10— 12 Number of copies to print (1-127) 

13 blank 

14 Whether spool job should be held 
(Y = yes, N = no) 

15 blank 

16 Whether spool job should be kept 
(Y = yes, N = no) 

17 blank 

18 — 21 Forms type 

22 blank 

23 — 30 Report identification 

31 blank 

32 Forms alignment (Y = yes, N = no) 

If you use the spool-control record, specify the fields exactly as shown. The fields 
with a Y/N option default to N. If you enter a character other than a Y or N, the 
system uses the default. 

Note: Do not generate the spool-control record in an application program unless 
spooUng has been activated. If spoohng is not active, the Hne is printed as ordinary 
text to the printer (see "Determining Whether Spoohng Is Active" on page 16-7 for 
a description of how an application program can determine if the spoohng facihty is 
active). 



Example 






The following program uses the spool-control record to create 10 copies with report 
identification SPOOLPRG, to hold and keep the output in effect, specify forms type 
ABCD, and specify no forms ahgnment. The report printed consists of two 
messages. 



i 



SPOOL 


PROGRAM START 


PRTR 


lOCB MPRTR 


START 


EQU * 




ENQT PRTR 




PRINTEXT ■***SPOOL 010 Y Y ABCD SPOOLPRG N" 




PRINTEXT '^MESSAGE 1' 




PRINTEXT '(BMESSAGE 2' 




DEQT 




PROGSTOP 




ENOPROG 




END 



Q Obtain exclusive use of the system printer. 

Q Create a spool-control record. Specify the number of copies as 10 (010), that 
you want to hold and keep the output (Y Y), that the type of forms is ABCD, that 
the report identification is SPOOLPRG, and that you do not require forms 
alignment (N). 

Q Create a hne of output. 
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Executing the Example 



To execute the example, you must do the following: 

1 Make sure that your system includes the spooling facility. To use the spooling 
facihty, you must include lOSPOOL at system generation time. (For 
information on how to include lOSPOOL in your supervisor, refer to the 
Installation and System Generation Guide.) 

2 Find out whether the device you want to use is a spool device. Use the 
$TERMUT1 utihty as follows: 



$L $TERMUT1 



The system responds: 

LOADING $TERMUT1 nnP, hh:mm:ss, LP= xxxx, PART= yy 
*** TERMINAL CONFIGURATOR *** 
COMMAND (?): 



Respond with the CT (Configure Terminal) command: 



COMMAND (?): CT 



The system prompts for the terminal name. Respond with the terminal name 
as follows: 



ENTER TERMINAL NAME: MPRTR 



The system then displays, one at a time, the parameters that define how the 
terminal operates. Since we are changing only the parameters, concerning 
whether or not the terminal is a "spoolable device," simply press enter until 
the system displays the SPOOLABLE prompt: 



PAGE SIZE 

OUTPUT PAUSE 
SPOOLABLE (Y/N) 



(NOW IS 



24) 



VALUE NOT CHANGED 



(NOW IS N): 

VALUE NOT CHANGED 
(NOW IS N): 
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If the system displays "NOW IS N," the terminal is not a spoolable device. 
Change the parameter to Y. 



SPOOLABLE (Y/N) 



(NOW IS N): Y 



Continue pressing enter until the COMMAND prompt appears. Then end the 
utihty: 



) 



COMMAND (?): EN 



J Tell the spool facihty that a device is a spool device. Use the $SPLUT1 utility 
as follows: 



> $L $SPLUT1 



The system responds: 

LOADING $SPLUT1 nnP, hh:mm:ss, LP= xxxx, PART= yy 

****************************************************** 

** EDX SPOOL UTILITY ** 

** CHANGES EFFECTIVE THE NEXT TIME $SPO0L IS LOADED ** 
****************************************************** 

DSNAME— V0LUME-MAXJOBS-MAXACTV-RESTRT-GRPS-GRPSZ-SEP--DEVICES-AUTO-F0RM 
SPOOL EDX0G3 10 4 Y 10 100 Y $SYSPRTR Y 

COMMAND {?): 






If the restart option is Y, change it to N. Enter the RS command: 



COMMAND (?): RS 



v.. 



The system responds: 



RESTART Y/N; 



Enter N and press enter. 



i J 
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The system responds: 

DSNAME— VOLUME-MAXJOBS-MAXACTV-RESTRT-GRPS-GRPSZ-SEP--DEVICES-AUTO-FORM 
SPOOL EDX003 IQ 4 N 10 100 Y $SYSPRTR Y 

COMMAND (?): 



Respond with the CD (Change Spool Devices) command: 



COMMAND (?): CD 



The system prompts for the terminal name. Respond with the terminal name 
as follows: 



DEVICE NAME (ENTER BLANK TO END): MPRTR 






The system then asks whether you want the spool job (the output of a 
program that generates spool output) to print as soon as the program 
completes. It also asks for the form number you want to use and whether you 
want to change another spool device. 

In this example, we are responding that we do not want the spool job to begin 
printing as soon as the program completes, that the forms code is ABCD, and 
that we do not want to change another spool device. 



WRITER AUTOSTART ? (Y/N) : M 

ENTER FORMS CODE: ABCD 

DEVICE NAME (ENTER BLANK TO END) 



Then end the utility: 



COMMAND (?): EN 



4 Load the spoohng facihty as follows: 



$L $SPOOL 



Note: Do not use the session manager to start the spool facihty. 
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If the spooling facility was not included at system generation time, the system 
responds with return code 8. 

Otherwise, the system responds: 



LOADING $SPOOL nnP, hh:mm:ss, LP= xxxx, PART= yy 

SPOOL INITIALIZATION COMPLETE 

..„. _., , / 

5 Start the program that generat :s the output that is to be spooled (in this case, 
program AP16A on volume EDX40). 

> $L AP16A,EDX40 

The system executes the program and places the output on the spool data set. 



The system then prompts for the forms code. Respond with the one- to 
four-character forms code (in our example, ABCD): 



FORMS: ABCD 



The system responds: 



WRITER STARTED 



and begins to print or display the spool job. 



o 



Printing Output That Has Been Spoofed 

To print output that has been spooled, use the $S operator command as follows: 



> $S WSTR 

U J 

The system prompts you for the writer name. Respond with the name of the device 
on which you want the spool job displayed or printed: 



WRITER NAME: MPRTR 

V 
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Stopping Spooling 

To stop spooling, use the $S operator command as follows: 



v_ 



> $S STOP 



Determining Whether Spooling Is Active 



An EDL application might be such that it should not be run unless spooling has 
been activated (or deactivated). Such an apphcation can determine if spoohng is 
active and use that information to instruct the operator to activate or deactivate 
spooling. An apphcation program can also decide v^hether or not to print a 
spool-control record, depending on whether or not spoohng is activated. 

The following EDL coding example shows how an apphcation program can 
determine if the spoohng facihty has been activated: 

n MOVE #2,$CVTSPL,FKEY=Q 

y IF #2,NE,0 

B MOVE #2,(+$IOSPSPM,#2),FKEY=0 

ENDIF 
Q IF #2,NE,0 



ENDIF 



I 



COPY PROGEQU 
COPY SIOSPTBL 



Q Move the address of the spool control table to register 2. 

Q Test whether module lOSPOOL was included at system generation time. 

Q If so, move the address of SPM to register 2. 

Q Test whether spooling has been activated. 

Q Copy the program equates to the program. 

Q Copy the spool table equates to the program. 

High-level language programs can call this type of EDL subroutine to determine if 
spooling is active. 
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Preventing Spooling 

You can prevent a program from spooling its output by coding a parameter on the 
ENQT command. The parameter is coded as follows: 

ENQT SPOOL=NO 

This instruction causes the printer to be enqueued directly, when available, and 
prevents output spooling. The system ignores the SPOOL = parameter on an ENQT 
instruction if the device is not designated as a spool device or if spooling is not 
active. 

The default is ENQT SPOOL = YES. This allows output spooling. 

Note; ENQT SPOOL = NO without the BUSY= operand coded causes the program 
to wait if a spool writer is started to the device, even if the writer is temporarily 
stopped. The writer must be terminated to free the device. Refer to the Language 
Reference for additional information. 

Separating Program Output into Several Spool Jobs 

When spooled output is directed to one printer, spooUng treats the spooled output 

from each task within a main program as a separate spool job. If there is a spool 

job open which belongs to the main task, and an overlay program generates spooled 

output, the system attaches this output to the main task's spool job. The system 

opens a spool job for an overlay program when a spool job for the main task does /^^ 

not exist. \.J^ 

You can produce more than one spool job within a single task. To do so, code the 
DEQT instruction as follows after you create each spool job. 

DEQT CLOSE=YES 

Each time you issue this instruction, the spool job just created becomes ready for 
printing. A subsequent ENQT to the same printer indicates the start of a new spool 
job. 

The CLOSE = operand is ignored if coded on a DEQT to a device not designated as 
a spool device or if spoohng is not active. 

Note: DEQT CLOSE = NO is the default. It causes any later output of the program 
directed to the same printer to be attached to the output already spooled. 



^^isJf^ 
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Programming Considerations 



After printing each spool job, the spool writer restores the default values established 
for the printer at system generation. Coding the PDEN, PMODE, LPI, and 
CHARSET operands on the TERMCTRL instruction does not change these 
defaults. You can spool a job using values for PDEN, PMODE, LPI, or CHARSET 
that differ from the default values by: 

• Changing the values for the PDEN, PMODE, LPI, or CHARSET operands on 
a TERMCTRL SET instruction inside the program being spooled 

• Using STERMUTl to change the values for the PDEN, PMODE, LPI, or 
CHARSET operands before the spool writer is started. 

If you want to spool a job changing only the value for the LPI operand, you can run 
a program that changes this value on the TERMCTRL SET instruction before 
$SPOOL is loaded. 
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f% Chapter 17. Creating, Storing, and Retrieving Program 

l\/lessages 

When designing EDL programs, you can save storage space or coding time by 
placing prompt messages and other message text in a separate message data set. 
EDL instructions enable your program to retrieve the appropriate message text when 
the program executes. 

By storing messages in a data set, you can change the text of a message without 
having to alter and recompile each program that uses that message. 

You can store program messages in two ways. You can store them on disk or 
diskette. You can also store them as a module that you can Hnk edit with a 
program. 

Creating and using your own program messages involves the following steps: 

1 . Creating a data set for your source messages 

2. Entering your source messages 

3. Formatting and storing your source messages using the message utihty, 
SMSGUTl 

4. Retrieving program messages using the COMP statement and the MESSAGE, 
GETVALUE, QUESTION or READTEXT instructions. 



f^^ 



The following sections describe how to create, store, and retrieve program messages. 



Creating a Data Set for Source l\/lessages 



You create a data set for source messages with the text editor described in 
Chapter 3, "Entering a Source Program." You can create one or more source 
message data sets and can store them on any volume. Messages can be simple 
statements or questions, or they can include variable fields which are filled with 
parameters supplied by your program. 

To enter your source messages, observe the following rules: 

• Begin each message in column 1 . 

• Precede each variable field with two less than symbols ( < < ) and follow each 
variable field with two greater than symbols ( > > ). 

• End each message with the characters: /* 

• Begin and end comments with double slashes (//comment//). A comment must 
be associated with a message. 

• Use the at sign (@) to cause the message to skip to the next line. 

• Code source messages a maximum length of 253 bytes long. You can calculate 
the length of a message by adding one byte for each character in the text and 
one byte for each variable field. 

• Continue a message on a new hne by coding any nonblank character in column 
72. Begin the continued hne in the first column. 
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The system identifies each message by its position in the source message data set. 
For example, the system assigns a message number of 3 to the third message in the 
source message data set. Once you format your source messages with the 
SMSGUTl utihty, you should add any new messages you have to the end of the 
source message data set. If you no longer need a certain message, you should leave 
it in the source message data set or replace it with a new message to preserve the 
numbering scheme. 

Coding Messages with Variable Fields 

To construct a message that can return information supphed or generated by your 
program, you can code a message with one or more variable fields. When you 
execute your program, the system inserts the appropriate parameters in these 
variable fields and prints a complete message. For example, if you want to construct 
a message that tells a program operator how many records are in a particular data 
set on a particular volume, you could code the following: 

THERE ARE «SIZE>S> RECORDS IN «DATA SET NAME>T> ON «VOLUME>T>./* 

The variable fields in the previous example are the number of records in the data set 
(SIZE), the data set name, and the volume name. The variable field names do not 
need to correspond with names in a program. 

Note: To print or display a message with variable fields, you must have included the 
FULLMSG module in your system during system generation. 

The variable fields are set off from the message text with two less than and two 
greater than symbols ( < < > >)■ The symbols should enclose a description of the 
field. The system treats the field description as a comment. You can include up to 
eight variable fields within a single message. 

As shown in the previous example, all variable fields must also contain a control 
character that describes the type of parameter your program will pass to the variable 
field. S is the control character in the field < < SIZE > S > ; T is the control 
character in the field < < VOLUME > T > . The following is a Ust of valid control 
characters and their descriptions: 

C Character data. Specify a length for the data by coding a value from 1 to 253 
before the "C" (for example, < <NAME>8C>). There is no default. 

T Text. No length is necessary. (The system derives the length from the TEXT 
statement.) 

H Hexadecimal data. The length is four EBCDIC characters. 

S Single-word integer. Specify a length for the data by coding a value from 1 to 
6 before the "S". The default is six EBCDIC characters. The vahd range for a 
single-word integer value is from - 32768 to 32767. 

D Double-word integer. Specify a length for the data by coding a value from 1 
to 11 before the "D." The default is six EBCDIC characters. The valid range 
for a double-word integer value is from -2147483648 to 2147483647. 
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Your program passes parameters to a message in the order you specified the 
parameters in the instruction. The following example shows a message instruction 
with the parameter list operand (FARMS = ): 

MSG PROGRAM START,DS=((MSGSET,EDXO03)) 



MESSAGE 2, COMP=ID,PARMS=(DSNAME, VOLUME, SIZE) 



ID COMP 'SRCE',DS1,TYPE=DSK 

SIZE DC F'lOO' 

DSNAME TEXT 'DATA SET 1' 

VOLUME TEXT ' EDXO02 ' 

The instruction will retrieve message number 2. The source message for message 
number 2 appears as follows: 

«DATA SET NAME>T> ON «VOLUME>T> IS ONLY «SIZE>S> RECORDS./* 

The system places the first parameter (DSNAME) in the first variable field, the 
second parameter (VOLUME) in the second field, and the third parameter (SIZE) in 
the third field. 

You may, however, want to alter or reword the message in the previous example. 
To change the order of the variable fields in your source message without changing 
the order of the parameter hst in your program, you can code an additional number 
after the control character. This number, from 1 to 8, points to the parameter that 
the system should insert into the variable field. The number corresponds to the 
position of the parameter in the parameter hst. For example, < < NAME > C3 > 
tells the system to retrieve the third parameter in a parameter list. 

In the following example, the order of the variable fields in message number 2 has 
been switched, but a number following the control character points to the correct 
parameter for the variable field: 

THERE ARE ONLY «SIZE>S3> RECORDS IN «DATA SET NAME>T1> ON C 

«V0LUME>T2>./* 

"S3" points to the third parameter in the Ust (SIZE), "Tl" points to the first 
parameter in the hst (DSNAME), and "T2" points to the second parameter in the 
hst (VOLUME). 
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Sample Source Message Data Set 

The following is sample of a source message data set. The data set is named 
SOURCE on volume EDX40. 

//THIS IS A COMMENT //+ 

DO YOU WANT TO ENTER A NUMBER? /* 

ENTER «TYPE OF VALUE>T> VALUE LESS THAN «VALUE>S>./* 

THE PROGRAM HAS PROCESSED THE INPUT DATA./* 

ENTER YOUR «FIRST/LAST/FULL NAME>10C>./* 

//THIS IS ANOTHER COMMENT. // + 

ALL INPUT DATA HAS BEEN RECEIVED./* 

THE VALUE YOU ENTERED IS: «VALUE>S1> /* 

THE DATA YOU ENTERED IS: «DATA>T> /* 

THE DEVICE «ID>H1> AT ADDRESS «DEVICE ADDRESS>H2> IS IN USE./* 

THIS MESSAGE WILL BE CONTINUED @ ON THE NEXT LINE./* 



Formatting and Storing Source Messages (using $IVISGUT1) 

Once you have created a source message data set, you must use the message utility, 
SMSGUTl, to convert the source messages into a form the system can use. The 
utility copies the source messages, formats them, and stores the formatted messages 
in another data set or module that you specify. (Refer to the Operator Commands 
and Utilities Reference for a detailed explanation of how to use the message utility.) 

Each time you add new messages to the source message data set, you must reformat 
the data set with SMSGUTl. 

The SMSGUTl utihty allows you to: 

• Format a source message data set and store the formatted messages on disk or 
diskette. 

• Format a source message data set as a module that you hnk edit with a 
program. Use this option for systems without disk or diskette storage or to 
improve performance. 

• Obtain a hard-copy hsting of the messages contained in a specific source 
message data set. 

Before you load the SMSGUTl utility, you must allocate a work file. You can use 
the AL command of the $DISKUT1 utihty to allocate the work file. Allocate a 
data-type data set large enough to hold the source message data set (one record for 
every source message). 

When you load SMSGUTl, the utility prompts you for the name and volume of the 
work file as follows: 



WORKFILE (NAME, VOLUME) 



Respond with the data set name and volume that you allocated with the SDISKUTl 
utility. 



\J 
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Example 1 






In the following example, $MSGUT1 formats the source message data SOURCE 
shown in the previous section. The example uses the DSK option and stores the 
formatted messages in the data set MESSAGE on volume EDX40. 



Example 2 



COMMAND (?): DSK 

MESSAGE SOURCE DATA SET (NAME, VOLUME) : SOURCE, EDX40 
DISK RESIDENT DATA SET (NAME, VOLUME): MESSAGE, EDX40 
START OF DISK MESSAGE PROCESSING BEGINS 



When the utihty finishes formatting and storing the messages, it returns the 
following message: 



DISK RESIDENT MESSAGES STORED IN MESSAGE, EDX40 



The following example uses the STG option and stores the module in data set MSG 
on volume EDX003. 



COMMAND (?): STG 

MESSAGE SOURCE DATA SET (NAME, VOLUME) : MSGSRC,EDX003 
STORAGE RESIDENT MODULE (NAME, VOLUME): MSG,EDX003 
START OF STORAGE MESSAGE PROCESSING 



When the utility finishes formatting and storing the messages, it returns the 
following message: 



STORAGE RESIDENT MODULE STORED IN MSG,EDX0Q3 



O 



If the $MSGUT1 utihty encounters errors, it prints an error message on the system 
printer. 
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Retrieving IVIessages 



To retrieve a message from storage and include it in your program, you must code a 
COMP statement and any one of the following instructions: MESSAGE, 
GETVALUE, QUESTION, and READTEXT. (Refer to the Language Reference 
for a full description of these instructions and how to code them to retrieve 
messages.) 

The system retrieves program messages from the data set or module that you created 
with SMSGUTl. If you stored your formatted messages on disk or diskette, you 
must code the name of the data set that contains the messages and the volume it 
resides on in the PROGRAM statement for your program. 

If you formatted the messages as a module, you must hnk edit your program with 
the module. 

Defining the Location of a Message Data Set 

The COMP statement defines the location of a message data set or the name you 
assigned the module when you used the STG option of the $MSGUT1 utihty. To 
retrieve a message, the MESSAGE, GETVALUE, QUESTION, and READTEXT 
instructions must refer to the label of a COMP statement. More than one 
instruction can refer to the same COMP statement. You must code a separate 
statement, however, for each message data set your program uses. 

If your messages are in a module, you must code the name of the module. If your 
message data resides on disk or diskette, you must indicate the data set in the 
PROGRAM statement. You indicate the correct data set by specifying its position 
in the data set list. 

In addition to coding the location of the message data set, you must also code a 
4-character prefix. The system prints this prefix and the number of the message you 
retrieved if you specify (MSGID = YES) on the MESSAGE, GETVALUE, 
QUESTION, or READTEXT instructions. 

The following example shows a COMP statement that refers to the second data set 
on the PROGRAM statement. DS2 points to data set MESSAGE on volume 
EDX40. 

MESSAGE PROGRAM START, DS= (DATA, (MESSAGE, EDX40)) 



PROGSTOP 
DISKMSG COMP 'ERRS' ,DS2,TYPE=DSK 

The following example shows a COMP statement that refers to a module that 
contains messages. 

MESSAGE PROGRAM START 



V, 



y 



PROGSTOP 
STGMSG COMP 'ERRS' ,MSG,TYPE=STG 
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The MESSAGE instruction 

The MESSAGE instruction retrieves a message from a data set on disk, diskette, or 
from a module. Then the instruction prints or displays the message. You must code 
the number of the message you want displayed or printed and the label of the 
COMP statement that gives the location of the message (COMP = ). 

You can pass parameters to variable fields in a message by coding the parameters on 
the PARMS= operand of the instruction. If you code MSGID = YES, the system 
prints or displays the number of the message and the 4-character prefix you coded 
on the COMP statement in front of the message text. 

In the following example, the MESSAGE instruction retrieves the third message in a 
message data set and passes the parameter PART# to the message. The COMP 
statement defines the message data set as the first data set in the PROGRAM 
statement hst. 

STOCK PROGRAM START, DS=( PARTS, DATA) 

MESSAGE 3,C0MP=PARTS,PARMS=PART#,MSGID=YES 



PROGSTOP 
PARTS COMP ■PART',DS1,TYPE=DSK 

PART# DC F'56' 

In the following example, the MESSAGE instruction retrieves the second message in 
a module that has been hnk edited with the program and passes the message the 
parameter PART#. The COMP statement defines the message data set as module 
MSG. 

STOCK PROGRAM START 

MESSAGE 2 ,COMP=PARTS , PARMS=PART# ,MSGID=YES 



PROGSTOP 
PARTS COMP 'PART', MSG, TYPE=STG 

PART# DC F'43' 
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The GETVALUE, QUESTION, and READTEXT Instructions 

Instead of coding prompt messages on the GETVALUE, QUESTION, and 
READTEXT instructions, you can retrieve prompt messages from a message data 
set or module. You code the number of the message you want to retrieve for the 
second operand of the GETVALUE and READTEXT instructions and the first 
operand of the QUESTION instruction. In addition, you must code the label of the 
COMP statement that gives the location of the message (COMP = ). 



You can pass parameters to variable fields in a message by coding the parameters on 
the PARMS= operand of the instruction. By coding MSGID = YES, the system 
prints or displays the number of the message and the 4-character name you coded on 
the COMP statement at the front of the message text. 

In the following example, the GETVALUE instruction retrieves the fifth message 
from a module, called MSGTEXT, that has been hnk edited with your program. 
The instruction also passes the message the parameters VALUE and SIZE to the 
message. 

GETVALUE INPUT, 5, COMP=PROMPT,PARMS=(VALUE, SIZE) 



PROGSTOP 

PROMPT COMP 'TASK', MSGTEXT, TYPE=STG 

VALUE TEXT 'AN INTEGER' 

SIZE DC F'75' 



In the following example, the GETVALUE instruction retrieves the ninth message 
from a data set on disk or diskette. The instruction passes the message the 
parameters VALUE and SIZE. 

BEGIN PROGRAM START, DS=MSGS 



GETVALUE INPUT, 9, COMP=PROMPT,PARMS=(VALUE, SIZE) 



PROGSTOP 

PROMPT COMP 'TASK',DS1,TYPE=DSK 

VALUE TEXT 'AN INTEGER' 

SIZE DC F'75' 
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Sample Program 






The following sample program retrieves five program messages from a disk data set 
formatted in the previous section. (See "Example 1" on page 17-5.) The name of 
the data set is MESSAGE and it resides on EDX40. 



I 



MESSAGE 
START 



NAME 



E 

m 



Bl 



PROGRAM 

QUESTION 

GETVALUE 

PRINTEXT 

PRINTNUM 

READTEXT 

PRINTEXT 

PRINTEXT 

MESSAGE 



MSG4 


EQU 


MSG6 


EQU 


MSG7 


EQU 


MSG9 


EQU 


DISKMSG 


COMP 


A 


DATA 


B 


TEXT 


PI 


TEXT 


P2 


DATA 


TXT 


DATA 




ENDPROG 




END 



START, DS=( (MESSAGE, EDX40) ) 

1,N0=NAME,SKIP=1,C0MP=DISKMSG 

A,2,SKIP=1,C0MP=DISKMSG,PARMS=(P1,P2) 

'(3THE NUMBER IS: ' 

A,SKIP=1 

B,+MSG4,SKIP=1,C0MP=DISKMSG,PARMS=TXT 

'@THE DATA ENTERED IS: ' 

B,SKIP=1 

+MSG6,C0MP=DISKMSG,SKIP=2,PARMS=A, 
MSGID=YES 
MESSAGE +MSG7 , COMP=DI SKMSG , SKI P=2 , PARMS=B , 

MSGID=YES 
MESSAGE +MSG9,C0MP=DISKMSG,SKIP=2,PARMS=B, 
MSGID=YES 
PROGSTOP 

4 

6 

7 

9 

'SRCE',DS1,TYPE=DSK 

F'0' 

LENGTH=40 

'AN INTEGER' 

F'lO' 

CLIG'LAST NAME ' 



Q Begin the program and identify the data set name and volume of the message 
data set (MESSAGE on volume EDX40). 

Display the prompt message DO YOU WANT TO ENTER A NUMBER? The 

first operand (1) identifies the message as the first message in the data set 
MESSAGE. The COMP= operand refers to a COMP statement labeled 
DISKMSG. If the operator enters Y, the next sequential instruction, the 
GETVALUE instruction, executes. If the operator enters A'', control passes to the 
label NAME. 

01 Use the second message in the message data set as a prompt message. The 
instruction retrieves the prompt message and inserts parameters PI and P2 into the 
message. The operator receives the prompt message ENTER AN INTEGER 
VALUE LESS THAN 10. 

01 Print the number the operator enters. 

Q Retrieve the fourth message (because MSGl is equated to 4) from the message 
data set and inserts parameter TXT into the message. The operator receives the 
prompt message ENTER YOUR LAST NAME. 

01 Print the name the operator enters. 
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Q Print or display the sixth message (because MSG6 is equated to 6) from the 
message data set. The COMP = operand refei's to the COMP statement labelled 
DISKMSG. The instruction uses the integer value the operator entered as the 
parameter for the message. If the operator entered a 6, for example, the system 
would print or display:THE VALUE YOU ENTERED IS 6. 

01 Print or display the seventh message (because MSG7 is equated to 7) from the 
message data set. The COMP = operand refers to the COMP statement labelled 
DISKMSG. The instruction uses the last name the operator entered as the 
parameter for the message. If the operator entered the name FRENCH, for 
example, the system would print or display: SRCE0007 THE DATA YOU 
ENTERED IS FRENCH. 

Q Equate MSG4 to the fourth message in the message data set. 



y| Define the message data set as the first data set on the PROGRAM statement. 
Identify the data set as a disk- or diskette-resident data set (TYPE = DSK). SRCE is 
the prefix that would appear if you coded MSGID = YES on a QUESTION, 
PRINTEXT, GETYALUE, or READTEXT instruction. 

m Define a parameter (used by the first MESSAGE instruction). 



The program uses the following source message data set: 

//THIS IS A COMMENT //+ 

DO YOU WANT TO ENTER A NUMBER? /* 

ENTER «TYPE OF VALUE>T> VALUE LESS THAN «VALUE>S>./* 

THE PROGRAM HAS PROCESSED THE INPUT DATA./* 

ENTER YOUR «FIRST/LAST/FULL NAME>10C>./* 

//THIS IS ANOTHER COMMENT. // + 

ALL INPUT DATA HAS BEEN RECEIVED./* 

THE VALUE YOU ENTERED IS: «VALUE>S1> /* 

THE DATA YOU ENTERED IS: «DATA>T> /* 

THE DEVICE «ID>H1> AT ADDRESS «OEVICE ADDRESS>H2> IS IN USE./* 

THIS MESSAGE WILL BE CONTINUED ^ ON THE NEXT LINE./* 

The program might produce output hke the following: 






DO YOU WANT TO ENTER A NUMBER? Y 

ENTER AN INTEGER VALUE LESS THAN 18: 4 

THE NUMBER IS: 4 

ENTER YOUR LAST NAME : OLIVER 

THE DATA ENTERED IS: OLIVER 

SRCE0OO6 THE VALUE YOU ENTERED IS: 4 

SRCE0OO7 THE DATA YOU ENTERED IS: OLIVER 

SRCE0OO9 THIS MESSAGE WILL BE CONTINUED 
ON THE NEXT LINE. 
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You can use the queue processing instructions of EDL to store and retrieve large 
amounts of data. You can retrieve data from a queue on either a first-in-first-out or 
last-in-first-out basis. 



Defining a Queue 






To define a queue, use the DEFINEQ statement. The following DEFINEQ 
statement defines a queue with ten queue elements. A queue element is either an 
address or data that you want to store. 

MSGQ DEFINEQ C0UNT=10 

The queue called MSGQ can contain ten 1-word addresses or 1-word data items. 

If you want to store data items that are longer than one word, code the SIZE 
operand as follows: 

QUEUE DEFINEQ C0UNT=15,SIZE=30 
The queue called QUEUE can contain 1 5 30-byte queue elements. 

Putting Data into a Queue 

To put data into a queue, use the NEXTQ instructions as follows: 
NEXTQ MSGQ,ADDR 



ADDR DATA F ' ' 

The instruction puts ADDR into the queue called MSGQ. ADDR can contain 
either one word of data or an address. 

To put more than one word of data into a queue, use the FIRSTQ instructions to 
find the address of the first storage area into which data can be moved. 

FIRSTQ QUEUE, #1 



QUEUE DEFINEQ C0UNT=15,SIZE=20 

The instruction puts into register 1 the address of the first storage area into which 
you can move twenty bytes of data. 

You could use the following instructions to prompt the operator for data and store 
the response in QUEUE: 

READTEXT ELEMENT, 'ENTER YOUR NAME; ' 
MOVE (0,#1), ELEMENT, (20, BYTE) 
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The READTEXT instruction prompts the operator and places the response in 

ELEMENT. The MOVE instruction moves the response to the address retrieved by ^_^ 

the FIRSTQ instruction. i ^ 

Retrieving Data from a Queue 

To retrieve data from a queue, use either the FIRSTQ or LASTQ instruction. 

Use the FIRSTQ instruction to retrieve the oldest entry from a queue. The 
following example 

FIRSTQ QUEUE, #2 
puts into register 2 the address of the oldest element in the queue called QUEUE. 

Use the LASTQ instruction to retrieve the newest entry from a queue. The 
following example 

LASTQ QUEUE, ADDR 
puts into ADDR the address of the oldest element in the queue called QUEUE. 

To transfer control if the queue becomes empty, code the EMPTY operand as 
follows: 

FIRSTQ QUEUE, ADDR, EMPTY=MT 



Example 



MT EQU 



ADDR DATA 



The instruction retrieves an element from the queue called QUEUE, puts the address 
of the element in ADDR, and causes a branch to MT if no more elements exist in 
the queue. 



The following example prompts the operator for 20 characters of data, stores the 
data in one queue, moves the addresses of the elements to another queue, and prints 
the elements on a first-in-first-out (FIFO) basis. 






^ijiy,,^!^ 
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Queue Processing 



QTEST PROGRAM START 
START EQU * 

DO 10, TIMES 

FIRSTQ QUEUE1,#1 

READTEXT MSG,' ENTER UP TO 20 CHARACTERS: ' 

MOVE (0,#1),MSG,(2O,BYTE) 

NEXTQ QUEUE2,#1,FULL=FULLQ 

ENDDO 

GOTO PRINT 
FULLQ EQU * 

PRINTEXT '@QUEUE2 FULL.' 
PRINT EQU * 

DO 10, TIMES 

FIRSTQ QUEUE1,#1,EMPTY=D0NE 

MOVE MSG,(O,#1),(20,BYTE) 

PRINTEXT MSG,SKIP=1 

NEXTQ QUEUE1,#1 

ENDDO 
DONE PROGSTOP 
B QUEUEl DEFINEQ C0UNT=10,SIZE=20 
EIQUEUE2 DEFINEQ C0UNT=10 
MSG TEXT LENGTH=20 

ENDPROG 

END 

Q Put the address of the oldest element into register 1 . 

Q Prompt the operator for twenty characters of data. Put the prompt in MSG. 

Q Move the operator's response into QUEUEl, to the address retrieved by the 
FIRSTQ instruction. 

Q Store in QUEUE2 the address where the response was stored in QUEUEl. 

Q Retrieve the oldest element from QUEUEl and put the address of the data into 
register 1. 

Q Move twenty bytes from the address pointed to by register 1 to MSG. 

B Print the data, skipping a hne between each data item (SKIP = 1). 

B Put back into QUEUEl the element retrieved by the FIRSTQ instruction. 

B Define a queue large enough to accommodate ten 20-character data items. 

IB Define a queue large enough to accommodate ten 1-word data items or 
addresses. 
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C Chapter 19. Writing Reentrant Code 






O 



Reentrant code is a group of instructions that can be executed simultaneously by 
more than one task in the same partition. Only one copy of the program that 
contains the reentrant instructions exists in storage at a given time. 

This chapter describes how to write reentrant EDL programs and subroutines and 
describes the following: 

• When to use reentrant code 

• Coding guidelines 

• Examples. 



When to Use Reentrant Code 

You should consider writing reentrant code when: 

• You don't want each task to have its own copy of the reentrant code. If the 
routine is called by several other tasks and occupies a large amount of processor 
storage, you may want to write reentrant code. 

• You don't want to enqueue the routine each time a task needs it. If a routine is 
called frequently, you may want to write reentrant code to avoid the problem 
that occurs when several tasks are waiting for a serially-reusable resource to 
become available. 



Coding Guidelines 

To write reentrant code, use the following guidehnes: 

• Avoid self-modifying instructions such as the use of the parameter-naming 
operands PI, P2, and P3. 

• Place all program variables in a storage area unique to the task that is executing. 
You can map these variables adjacent to the task control block (TCB) and 
access them as a displacement from the TCB. 

You can obtain the TCB address with the TCBGET instruction as follows: 

TCBGET #1 

This instruction puts the address of the TCB in register 1 . 

Notes: 

1. If you place the variables ahead of the TCB, avoid using the TCB generated 
by the ENDPROG statement because the compiler may put data between 
the mapped variables and the main task control block. 

2. If you place the variables after the TCB, ensure that all TCBs are the same 
length. Inconsistent use of the FLOAT operand of the TASK or 
PROGRAM statement can cause TCBs to be different lengths. 
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Use only instructions that are reentrant. 

You can use the instructions that are not reentrant, however, by "protecting" /if"^ 

them with the ENQ and DEQ instructions. For example, if you want to use a \^ 

subroutine in reentrant code, a CALL to a subroutine might look Hke this: 



ENQ SUB4QCB 
CALL SUB4,... 
DEQ SUB4QCB 



Note: Any code that you place between the ENQ and DEQ statements is 
serially reusable but not reentrant. 

The following instructions are not reentrant: 

- CALL 

- CONCAT 

- DOx,TIMES 

- DSCB or any instruction that uses a DSCB: 

- GIN 

- LOAD$DISKUT3 

- LOADPGMx 

- NOTE 

- POINT 

- READ 

- WRITE 

- GETEDIT 

- GETVALUE with the FORMAT operand 

- lODEF 

- PLOTGIN 

- PRINTNUM with the FORMAT operand 

- PUTEDIT 

- SCREEN 

- SUBROUT 

- XPLOT 

- YPLOT 
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Examples 



This section contains two examples. 



Example 1 consists of a main task and two subtasks. The main task, containing the 
reentrant code, and the two subtasks all transfer control to the reentrant code. 



Example 2 shows how to make a nonreentrant routine into a reentrant routine, 
also shows how to execute the reentrant routine from three tasks. 



It 



Example 1 



The following example consists of a main task and two subtasks. The main task and 
the two subtasks all transfer control to a group of reentrant instructions with the 
label RENTER. The reentrant instructions perform two additions and print the 
result. Each task prints the results on a different terminal. 



The next two pages contain the reentrant code and the main task. The two subtasks 
are contained on the two subsequent pages. 



y 



TCB 


PROGRAM START 


1 RENTER 


ADD 
ADD 

PRINTEXT 
PRINTNUM 


(0,#1),(2,#1),RESULT=(4,#1) 

(0,#1),1 

(10, #1) 

(4,#1) 


1 


GOTO 


(6,#1) 


START 


LOAD 


TASKl , PASSPARM, EVENT=ECB1 


LOAD 


TASK2 , PASSPARM, EVENT=ECB2 




MOVEA 


#1,PARM 




ENQT 

DO 

GOTO 


$SYSPRTR 

100 

RENTER 


j LM 


ENDDO 
DEQT 




1 


WAIT 


ECBl 


1 


WAIT 


ECB2 




PROGSTOP 


g PASS PARM 


DC 


A(RENTER) 


i 1 ^^^^ 


ECB 





1 [ ECB2 


ECB 





j j PARM 

1 ; 

1 


DC 
DC 
DC 
DC 


F'l' 
F'l' 
F'O' 
A(LM) 


TEXT 


■©ANSWER FROM MAIN TASK = ' 




ENDPROG 




END 
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Q Begin the reentrant routine. Add the first two data areas in the parameter area 
and place the result in the third word of the parameter area. 

Q Add 1 to the first word of the parameter area. 

Q Print the message that begins at the fifth word of the parameter area. 

01 Print the result of the ADD instructions. 

Q Transfer control back to the task from which control was transferred. 

B Attach the first of the two subtasks (TASKl). Pass the address of the reentrant 
routine in PASSPARM. Identify ECB2 as the event to be posted when the task has 
completed. 

Q Attach the second of the two subtasks (TASK2). 

Q Move the address of PARM to register 1 . PARM contains the numbers the 
reentrant instructions will add, a data area for the result, an address (to which the 
reentrant routine will branch), and a message used to display the result. 

Q Get exclusive use of the system printer. 

03 Begin a DO loop. Execute the DO loop 100 times. 

EQ Transfer control to the reentrant routine. 

[Q End the DO loop. 

IQ Release exclusive use of the system printer. 

[Q Wait for TASKl to complete. 

ES Wait for TASK2 to complete. 

IQ Define the address of the reentrant instructions as an address constant. 

BH Define event control blocks for the two subtasks. 

113 Define the data areas to be added. The main task uses these data areas. 

10 Define the data area for the result of the ADD instruction. 

03 Define the address to which the reentrant routine transfers control. 

Define the message to be printed. 



/tT^ 






19-4 SC34-0943 



Writing Reentrant Code 









j TCB 


PROGRAM 


START, PARM=1 




j START 


MOVEA 


#1, PARMl 




{ 


ENQT 


SSYSPRTR 






DO 
GOTO 


100 
($PARM1) 




LI 


ENDDO 






m 


DEQT 

PROGSTOP 

ENDPROG 






Q PARMl 


DC 


FT 




■ 


DC 


F'2' 




X 


DC 


F'O' 




S 


DC 


A(L1) 




^ 


TEXT 
END 


'0ANSWER FROM TASKl 


^ 


^ TCB 


PROGRAM 


START, PARM=1 




START 


MOVEA 


#1, PARMl 






ENQT 


$SYSPRTR 






DO 


100 






GOTO 


($PARM1) 




LI 


ENDDO 

DEQT 

PROGSTOP 






g PARMl 
s: 

S ( 


ENDPROG 
DC 


F'l' 




DC 
DC 
DC 


F'5' 
F'O' 
A(L1) 




! : 


TEXT 
END 


'©ANSWER FROM TASK2 


= 



Begin TASKl. Identify START as the first instruction to be executed and 
specify that one parameter will be passed to the program (PARM = 1). The 
parameter being passed is the address of the reentrant routine. 

Ql Move the address of PARMl to register 1. PARMl contains the numbers the 
reentrant instructions will add, a data area for the result, an address (to which the 
reentrant routine will branch), and a message used to display the result. 



3 Get exclusive use of SSYSPRTR. 

Begin a DO loop. Execute the DO loop 100 times. 
03 Transfer control to the reentrant routine. 
E3 Release exclusive use of $SYSLOG. 

J Define the data areas to be added. 
Ql Define the data area for the result of the ADD instruction. 
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Bol Define the address to which the reentrant routine transfers control. 
Define the message to be printed. 



o 



E3 Begin TASK2. Identify START as the first instruction to be executed and 
specify that one parameter will be passed to the program (PARM = 1). The 
parameter being passed is the address of the reentrant routine. 

E9 Define the data areas for TASK2. 



Example 2 



This example consists of three sections. The first section shows instructions that are 
not reentrant. The second section shows the same instructions made reentrant. The 
third section shows one way the reentrant instructions can be executed. 



The Nonreentrant Instructions 

The following instructions produce a random number, add it to itself ten times, and 
print the result. The DO loops and the PRINTEXT and PRINTNUM instructions 
make the program nonreentrant. 



PROGl 


PROGRAM 


STPGM 




COPY 


TCBEQU 


STPGM 


DO 


10, TIMES 


MOVE 


COUNT, 


MOVE 


SUM,0 


MOVE 


RNBRl, 


MULTIPLY 


RNDCON , RNBR2 , RESULT=RNBR1 , PREC=DSD 


SHIFTR 


RNBR1,6,RESULT=C0UNT 




DO 


10, TIMES 


ADD 


SUM, COUNT 




ENDDO 




D 


STIMER 


COUNT, WAIT 




PRINTEXT 


'@A(TCB):' 


ICT 


PRINTNUM 


PR0G1+$TCBVER,M0DE=HEX 




PRINTEXT 


' COUNT: ■ 


ID 


PRINTNUM 


COUNT 




PRINTEXT 


' SUM:' 


m 


PRINTNUM 
ENDDO 


SUM 


El 


TERMCTRL 
PROGSTOP 


DISPLAY 


RNDCON 


DATA 


D'65539' 


RNBRl 


DATA 


F'O' 


RNBR2 


DATA 


F'9999' 


COUNT 


DATA 


F'O' 


SUM 


DATA 

ENDPROG 

END 


F'O' 



^btoflK'^ 
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Q Execute the loop 10 times. 

Q Initialize COUNT to 0. 

B Initialize SUM to 0. 

Q Initialize RNBRl to 0. 

Q Generate a random number, using the number 9999 as a "seed." Put the result 
in RNBRl. (PREC = DSD causes the result to be placed in a two-word (double 
precision) data area, the first word of which is RNBRl. The rightmost word of the 
result, however, is placed in the next word (RNBR2). The second time this 
instruction executes, the result is different because operand 2 (RNBR2) has 
changed.) 

Note: The instructions that generate the random numbers are used for illustrative 
purposes only. 

01 Shift the result of the previous MULTIPLY instruction. Put the result in 
COUNT. This instruction takes the result of the MULTIPLY instruction and 
makes the number smaller. 

B Execute another loop ten times. 

B Add COUNT to SUM. 

B Tell the system to wait the number of milliseconds contained in COUNT. 

3 Print the address of the TCB in hexadecimal (MODE = HEX). 

Print the random number. 

IB Print the result of the addition. 

IB Display the data in the system buffer. 
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The Same Instructions Made Reentrant 

The following instructions do exactly the same thing as the previous nonreentrant 
instructions. They produce a random number, add it to itself ten times, and print 
the result. The DO loops and the PRINTEXT and PRINTNUM instructions have 
been changed to make the instructions reentrant. 



PROGl 


PROGRAM 


STPGM 




1 


COPY 


TCBEQU 




1 STPGM 


TCBGET 


#1,$TCBVER 






MOVE 


(+LCNT1,#1),10 






DO 


WHILE, ((+LCNT1,#1),NE,0) 




1 


SUBTRACT 


(+LCNT1,#1),1 




1 


MOVE 


(+COUNT,#1),0 






MOVE 


(+SUM,#1),0 






MOVE 


(+RNBR1,#1),0 




1 


MULTIPLY 


RNDCON, (+RNBR2,#1),RESULT=(+RNBR1,#1), PR 


EC=DSD 




SHIFTR 


(+RNBR1,#1),6,RESULT=(+C0UNT,#1) 






MOVE 


(+LCNT2,#1),1G 




r 


DO 


WHILE, ((+LCNT2,#1),NE,0) 




f 


SUBTRACT 


(+LCNT1,#1),1 




n 


ADD 
ENDDO 


(+SUM,#1),(+C0UNT,#1) 




i 


STIMER 


(+C0UNT,#1),WAIT 




ENQ 


PRTLINE 






PRINTEXT '@A(TCB):' 




IQ 


PRINTNUM 


(+$TCBVER,#1),M0DE=HEX 






PRINTEXT ' COUNT:' 




EB 


PRINTNUM 


(+C0UNT,#1) 






PRINTEXT ' SUM:' 




E 


PRINTNUM (+SUM,#1) 




DEQ 


PRTLINE 






ENDDO 






IH 


TERMCTRL 


DISPLAY 






PROGSTOP 




B51 PRTLINE 


QCB 






RNDCON 


DATA 


D' 65539' 








; 



TWKAREA 
RNDSEED 

TCBADDR 

RNBRl 

RNBR2 

COUNT 

SUM 

LCNTl 

LCNT2 



ENDPROG 

DATA 

DATA 

DATA 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

END 



F'O' 

F'9999' 

4F'0' 

*-PR0Gl 

RNBRl+2 

RNBR2+2 

COUNT+2 

SUM+2 

LCNTl+2 
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Writing Reentrant Code 

Q Copy the task control block (TCB) equates into the program. 

01 Put the address of the TCB in register 1 . 

Q Initiahze the loop counter to 10. 

Q Execute the loop ten times. 

01 Subtract 1 from the loop counter. 

Q Initiahze COUNT to 0. 

B Initiahze SUM to 0. 

B Initiahze RNBRl to 0. 

Q Generate a random number, using the number 9999 as a "seed." Put the result 
in RNBRl. (PREC = DSD causes the result to be placed in a 2- word (double 
precision) data area, the first word of which is RNBRl. The rightmost word of the 
result, however, is placed in the next word (RNBR2). The second time this 
instruction executes, the result is different because operand 2 (RNBR2) has 
changed.) 

Note: The instructions that generate the random numbers are used for illustrative 
purposes only. 

Ifoi Shift the result of the previous MULTIPLY instruction. Put the result in 
COUNT. This instruction takes the result of the MULTIPLY instruction and 
makes the number smaller. 

m Initiahze another loop counter. 

in Execute another loop ten times. 

Bel Subtract 1 from the loop counter. 

[Q Add COUNT to SUM. 

id Tell the system to wait the number of miUiseconds contained in COUNT. 



Gain exclusive control of the next six instructions. This instruction is necessary 
to avoid "interleaving" of output. Interleaving could occur if more than one task 
executed the six instructions at the same time. 

IH Print the address of the TCB, COUNT, and SUM. 

IB Rehnquish control of the resource (the six output instructions). 
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J Display the data in the system buffer. 
03 Define a queue control block. 



Point to the task control block, 
control block. 



The ENDPROG statement generates a task 



[^ Point to the area immediately preceding the task control block. TWKAREA 
minus TCBADDR produces a negative number. When the program loads the TCB 
address into register 1 and uses RNBRl, RNBR2, COUNT, SUM, LCNTl, or 
LCNT2 as a displacement, the result points to a variable with the unique storage 
area associated with the attaching task. The unique storage area must immediately 
precede the TCB. 

Executing a Reentrant Program 

The following instructions show how to execute the reentrant routine from three 
tasks. The reentrant routine begins at label STTSK. 



PR0G3 


PROGRAM 


STPGM 


STPGM 


ATTACH 


TASKl 




ATTACH 


TASK2 




ATTACH 


TASK3 




WAIT 


EVENTl 




WAIT 


EVENT2 




WAIT 


EVENTS 




TERMCTRL 


DISPLAY 




PROGSTOP 


-1 


TASKl 


TASK 


STTSK, EVENT=EVENT1 




DATA 


F'O' 




DATA 


F'9999' 




DATA 


4F'0' 


TASK2 


TASK 


STTSK, EVENT=EVENT2 




DATA 


F'O' 




DATA 


F'9999' 




DATA 


4F'0' 


TASK3 


TASK 


STTSK, EVENT=EVENT3 




DATA 


F'O' 




DATA 


F'9999' 




DATA 


4F'0' 


RNBRl 


EQU 


*-TASK3 


RNBR2 


EQU 


RNBRl+2 


COUNT 


EQU 


RNBR2+2 


SUM 


EQU 


COUNT+2 


LCNTl 


EQU 


SUM+2 


LCNT2 


EQU 


LCNTl+2 


STTSK 


TCBGET 


#1,$TCBVER 



=y 



m 



ENDTASK 
ENDPROG 
END 






19-10 SC34-0943 



Writing Reentrant Code 

D Attach the first task (TASKl). 

01 Attach the second task (TASK2). 

Q Attach the third task (TASKS). 

Q Wait for the completion of the first task (TASKl). 

01 Wait for the completion of the second task (TASK2). 

Q Wait for the completion of the third task (TASK3). 

Q Display the contents of the buffer, 

Q Define a task with the label TASKl. The label of the first instruction to be 
executed is STTSK. Identify EVENT 1 as the event to be posted when the task 
completes. 

01 Define data areas that are unique to TASKl. 



y Define a task with the label TASK2. The label of the first instruction to be 
executed is STTSK. Identify EVENT2 as the event to be posted when the task 
completes. 

m Define data areas that are unique to TASK2. 

[Q Define a task with the label TASKS. The label of the first instruction to be 
,.^' executed is STTSK. Identify EVENTS as the event to be posted when the task 

completes. 

IH Define data areas that are unique to TASKS. 

Use equates to map the task data areas. 

Begin the reentrant code. 

9 End the reentrant code. 
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Chapter 20. Accessing $SYSCOM through a Program 

You can access the system common data area (known as SSYSCOM) through an 
EDL program. Programs in any partition can access SSYSCOM and use the 
common data area to store information. 

Before you can access SSYSCOM through a program, you must define SSYSCOM 
at system generation time. To do so, modify the SEDXDEF data set. For more 
information on how to do this, refer to the Installation and System Generation Guide. 

This chapter provides two sample EDL programs that access SSYSCOM. The 
chapter describes how SSYSCOM must be defined in the SEDXDEF data set in 
order for the sample programs to execute. 



Sample Program A 



An explanation of the numbered items follows the program. 



PROGA 


PROGRAM 


START 


START 


MOVE 


#1, SSYSCOM, FKEY=0 




TCBGET 


SAVEADS, $TCBADS 




TCBPUT 


ZERO,$TCBADS 


ENQ 


(PRINTER,#1) 




DEQ 


(PRINTER, #1) 


POST 


(EVENTl, #1) 




TCBPUT 
PROGSTOP 


SAVEADS, STCBADS 


SAVEADS 


DATA 


F'O' 


ZERO 


DATA 


F'O' 


PRINTER 


EQU 





EVENTl 


EQU 

ENDPROG 
END 


PRINTER+10 
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Q Store the address of the data common area ($SYSCOM) in index register 1 . 

B Save the current TCB address ($TCBADR). 

B Set the TCB address ($TCBADR) to zero for the QCB and ECB in SSYSCOM. 

B Obtain exclusive use of the resource PRINTER. (PRINTER is defined in the 
SEDXDEF data set.) 

B Release exclusive use of the resource PRINTER. (PRINTER is defined in the 
SEDXDEF data set.) 

B Post the ECB in the data common area called EVENT 1. 

B Restore the TCB address ($TCBADR). 

In order for Program A to execute, define SSYSCOM in the $EDXDEF data set as 
follows: 



$SYSCOM 


CSECT 




PRINTER 


QCB 




EVENTl 


ECB 






ENTRY 


SEDXPTCH 


$EDXPTCH 


DATA 
END 


128F'Q' 



Sample Program B 



An explanation of the numbered items follows the program. 






PROGB 


PROGRAM 


START 

BUF 
NAME 


MOVE 


MOVEA 
MOVE 


MOVE 
MOVE 
DATA 


EQU 


STREET 


EQU 


CITY 


EQU 




PROGSTOP 




ENDPROG 




END 



START 

#1,$SYSCOM,FKEY=0 

#2, BUF 

(NAME, #2) , (NAME,#1) , (20, BYTES) ,FKEY=0 

(STREET, #2) , (STREET, #1) , (20, BYTES) , FKEY=0 

(CITY, #2) , (CITY,#1) , (20, BYTES) ,FKEY=0 

60C' ' 

NAME+20 
STREET+20 
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Q Move the address of the common area (SSYSCOM) to index register 1 . 

Q Move the address of BUF to index register 2. 

Q Move NAME from the common area to the first 20 characters of BUF. 

Q Move STREET from the common area to the second 20 characters of BUF. 

Q Move CITY from the common area to the last 20 characters of BUF. 

Q Define a 60-character area to receive the data items from the common area. 

Q Map the structure of the common area. 

Q Map the structure of the common area. 

Q Map the structure of the common area. 

In order for Program B to execute, define SSYSCOM in the SEDXDEF data set as 
follows: 

$SYSCOM CSECT 

NAME DATA 20C' ' 

STREET DATA 20C' ' 

CITY DATA 20C' ' 

ENTRY $EDXPTCH 

$EDXPTCH DATA 128F'0' 

END 
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Appendix A. Tape Labels 



The following is the layout of the VOLl label: 



Field Name 


Bytes 


Initialized < 


Label identifier 


3 


VOL 


Volume label number 


1 


1 


Volume serial 


6 


xxxxxx 


Volume security 


1 





Data file directory 


10 


blanks 


Reserved 


10 


blanks 


Reserved 


10 


VOL 


Owner name 


10 


NAME 


Reserved 


29 


blanks 



The following is the layout of the HDRl label: 



^^ 



Field Name 


Bytes 


Initialized Com 


Label identifier 


3 


HDR 


File label number 


1 


1 


File identifier (DSN) 


17* 


Data set name 
(DSN) 


File serial number 


6 


XXXXXX 


Volume sequence 


4 


0001 


number 






File sequence number 


4 


OONN 


Generation number 


4 


blanks 


Generation version 


2 


blanks 


number 






Creation date 


6 


YYDDD 


Expiration date 


6 


YYDDD 


File security 


1 





Block count 


6 


000000 


System code 


13 


IBMEDXl 


Reserved 


7 


blanks 



* EDX supports an 8-byte, nonblank data set name (DSN). EDX ignores the last 9 
bytes of the DSN. 
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^ Appendix B. Interrupt Processing 



Interrupts apply to the interaction between a program and a terminal operator. For 
example, a program can wait for an interrupt, such as an operator response to a 
prompt, or a terminal operator can cause an interrupt by pressing a Program 
Function key. 

When an interrupt occurs, if it is completing an outstanding operation, control is 
returned to the next sequential instruction if there are no errors. If the interrupt was 
unsolicited (caused by the attention key or a PF key), then either the system or user 
ATTNLIST begins executing as an asynchronous task competing for system 
resources. 



interrupt Keys 



The keys that can cause interrupts are the attention key. Program Function (PF) 
keys, and the enter key. 



The Attention Key 

When the attention key is recognized, the greater than symbol ( > ) is displayed and 
the operator can enter either a system function code (for example, $L) or a program 
function code defined in an ATTNLIST. 



If you have this terminal type 


Then this is your attention key 


4978/4979 


The key marked ATTN 


Teletype 


The ESC (escape) key 


3101 Display Terminal 


The ALT and F8 key 


3151/316X Terminal 


The F8 key 



Note: The term 316x refers to the 3161, 3163 and 3164 terminals. 

Program Function (PF) Keys 

Any program function key on the 4978/4979, 3101, 3151 and 316x is recognized by 
the attention list code $PF (except for a PF key defined as the attention key). In 
addition, individual keys can be recognized separately by $PF1 to $PF254. You can 
provide separate entry points to the application code for particular keys, or a single 
entry point for all keys or a group of keys for rapid response. 

The order of the PF keys in the attention hst is significant because it defines the 
entry points to the application code. For example: 

ATTNLIST ($PF1,ENT1,$PF5,ENT2,$PF,ENT3) 
causes the program to be entered at ENT3 for all PF keys except PFl and PF5. 

On the 4978/4979, pressing the PF6 key causes the screen image to be printed on any 
designated hard-copy terminal (unless that terminal is a spool device and spool is 
loaded). This is not true for PF6 on the 3101. 
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The 3101 keyboard has eight PF keys. EDX supports these keys when the 3101 is 
operated in both character and block mode. To use the PF keys on the 3101, hold 
down the ALT key (on the lower right-hand side of the keyboard) while you press 
the appropriate numeric key. 

The 3151/316x keyboards have 12 PF keys (labeled Fl through F12). EDX supports 
these keys in either character or block mode. 






Enter Key 



The enter key indicates the end of typed input, for example, the end of the operator 
input for a READTEXT instruction. You also use it in conjunction with the WAIT 
KEY instruction. 



If you have this terminal type 


Then this is your enter key 


4978/4979 


The key marked ENTER 


3101 in block mode 


The Send key 


3101 in character mode 


The new line key 


3151/3 16x in block mode 


The Send key 


3 1 5 1 /3 1 6x in character mode 


The new line key 



Instructions that Process Interrupts 



Instructions that process interrupts are READTEXT, GETVALUE, WAIT KEY 
and ATTNLIST. 



o 



The READTEXT and GETVALUE Instructions 

In many cases a program needs to wait for an interrupt, such as an operator 
response to a request for input. This program- wait capability is provided 
automatically by the READTEXT and GETVALUE instructions. These 
instructions have an "implied wait." They wait for the terminal operator to enter 
data and press the enter key. 

The WAIT KEY Instruction 

An application program can wait at any point for a 4978/4979 or 3101 terminal 
operator to press the enter or one of the PF keys. This is done by issuing the WAIT 
KEY instruction. 

When the enter or a PF key is pressed, the program resumes operation, and the key 
is identified to the program in the second task code word at taskname + 2. The code 
value for the enter key is 0. The value for a PF key is the integer corresponding to 
the assigned function code; 1 for PFl, 2 for PF2, and so on. 

The PF keys do not initiate attention list processing during execution of the WAIT 
KEY instruction. They only cause the WAIT KEY instruction to terminate, 
allowing subsequent instructions to be executed. 
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The ATTNLIST Instruction 

The ATTNLIST instruction provides entry to interrupt processing routines. When a 
PF key is pressed, the ATTNLIST task for that key gets control if ATTNLIST was 
coded in the application program. If ATTNLIST was not coded, the system search 
for a PF key match fails and the message "FUNCTION NOT DEFINED" is 
displayed on the screen. Except for the 4978/4979 hard-copy print key (normally 
PF6), the 4978 attention key (normally PFO) and the 3101 attention key (normally 
PF8), the PF keys are always matched against user-written ATTNLIST(s) as 
described above. 

When the attention key on a terminal is pressed, the system prompts the operator for 
a command. This command is first matched against the system ATTNLIST and 
then against user- written ATTNLIST(s). 

If the command matches the system ATTNLIST, appropriate system action is taken 
(for example, $D or $L) unless the task is busy. If the command entered was $C, 
SVARYON, or $VARYOFF and this task is busy, the message " > NOT 
ACKNOWLEDGED" is displayed; when the task is completed, $C, SVARYON, or 
SVARYOFF is then executed. If the command entered was $P or $D and this task 
is busy, the command is ignored. 

If the command matches a user-written ATTNLIST, the corresponding ATTNLIST 
task gets control. The appropriate application program attention routine then runs 
under this task. If the attention key loaded the ATTNLIST and the task is already 
busy, the message " > NOT ACKNOWLEDGED" is displayed on the terminal. 

If there is no match against any ATTNLIST, the message "FUNCTION NOT 
DEFINED" is displayed. 

When the ATTNLIST task for a PF key gets control, the code for that key is placed 
in the second word of the ATTNLIST task control block. You can obtain the code 
for an interrupting key by coding the TCBGET instruction. 



Advance Input 



As a terminal user, your interaction with an application or utility program is 
generally conducted through prompts which request you to enter data. Once you 
have become famiUar with the dialogue sequence, however, prompting becomes less 
necessary. The READTEXT and GETVALUE instructions include a conditional 
prompting option which enables you to enter data in advance and thereby inhibit the 
associated prompts. 

Advance input is accomplished by entering more data on a line than has been 
requested by the program. Subsequent input instructions specifying 
PROMPT = COND will read data from the remainder of the buffered Hne, and issue 
a prompt only when the pre-entered data has been exhausted. If you specify 
PROMPT = UNCOND with an input instruction, an associated prompt is issued and 
the system waits for input. The prompt causes, as does every output instruction, 
cancellation of any outstanding advance input. 
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Defining Logical Screens 



A logical screen is a screen defined by margin settings, such as the TOPM, BOTM, 
LEFTM and RIGHTM parameters. Logical screens can be defined either during 
system generation (using the TERMINAL statement) or at the time an ENQT 
instruction is executed (using the lOCB statement). 

UsinGj TERMINAL to D6ffBri@ 3 LoqicsiI Scrosn 

The following example of using ,the TERMINAL statement defines a static screen to 
be used for data entry and display. Programs can be loaded from the terminal, but 
the terminal I/O instructions issued will be interpreted for a static screen unless the 
configuration is changed to roll by an lOCB statement. This is a typical definition 
for a terminal to be used for data entry. 

TERM2 TERMINAL DEVICE=4979,ADDRESS=14,SCREEN=STATIC 

The next example shows a spUt screen configuration. The roll screen is the bottom 
12 lines of the screen; the top half can be used for other logical screens defined upon 
execution of ENQT. 

TERM3 TERMINAL DEVICE=4978,ADDRESS=24,T0PM=12,NHIST=6 

The next example defines a roll screen occupying the upper-right quadrant of the 
screen. In general, logical screens with less than an 80-character Une size suffer some 
performance disadvantages (such as slower erasure) but can be useful for special 
apphcations. Note that NHIST is zero here because screen shifting will not be 
performed; a nonzero value for NHIST would merely cause the history area to be 
unused. 

TERM4 TERMINAL DEVICE=4979,ADDRESS=34,LEFTM=39, C 

B0TM=11,NHIST=0 

The final example defines a static screen for the 3101 in block mode. The 3101, 
3151, 3161, 3163, and 3164 terminals can have only a single roll screen or static 
screen. The Multifunction Attachment is used to connect the terminal to the 
Series/ 1. 

TERM5 TERMINAL DEVICE=ACCA,ADDRESS=59,MODE=3101B, C 

SCREEN=STATIC,LM0DE=RS422,ADAPTER=MFA 
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Using lOCB and ENQT to Define a Logical Screen 

Logical screens can also be defined by the ENQT instruction referencing an lOCB. 
The lOCB statement is used to define many of the "soft" characteristics of a 
terminal (such as margins, page size or hne length) and to estabUsh the connection 
between the ENQT and TERMINAL statements at execution time. Using an 
ENQT instruction which references an lOCB, you can modify the soft characteristics 
of a specific terminal defined by the TERMINAL statement. The lOCB statement 
and its operands are described fully in the Language Reference. 

In the following example, the lOCB labeled TOPHALF defines the top half of the 
screen (from which the program was loaded) as a static screen. If the terminal were 
defined as in TERM3 on the previous page, the program could have been loaded by 
entering $L program-name in the roll screen area (the bottom half of the screen). 
Since no terminal name is specified on the lOCB statement, the ENQT refers to the 
loading terminal. The program then might display tabular information on the static 
screen, execute DEQT and then end. The information displayed on the static screen 
part of the screen will remain on the screen while the terminal operator performs 
other operations using the roll screen. 

DISPLAY PROGRAM BEGIN 

TOPHALF lOCB B0TM=11,SCREEN=STATIC 

BEGIN ENQT TOPHALF 



DEQT 

PROGSTOP 
ENDPROG 
END 



The next example shows terminal access by using the symbolic name of the terminal. 
TERMl, TERM2, TERMS, and TERM4 have all been defined with TERMINAL 
configuration statements. The use of a static screen ensures that only physical hne 
of each screen will be altered. (LINE = for roll screens causes a page eject and 
erasure of information.) 

Note: On a 4979, unprotected fields should be of even length. 



NOTICE 


PROGRAM 


BEGIN 


TERMX 


lOCB 


SCREEN=STATIC 


NAMETAB 


DATA 


CL8' TERMl' 




DATA 


CL8'TERM2' 




DATA 


CL8'TERM3' 




DATA 


CL8'TERM4' 


BEGIN 


MOVEA 


#1, NAMETAB 




DO 


4 




MOVE 


TERMX, (0,#1), (8, BYTES) 




ENQT 


TERMX 




PRINTEXT "SYSTEM ACTIVE ',LINE=0 




DEQT 






ADD 


#1,8 




ENDDO 






PROGSTOP 






ENDPROG 






END 
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Structure of the lOCB 

The structure of the lOCB is given in the following table. The structure may change 
with future versions of the Event Driven Executive. 



Field Name 

Terminal name 

Flags 8 

Top of working area 9 



Byte(s) Contents 

0-7 EBCDIC, blank filled 



Bit "off indicates that the name is the only 
element of the lOCB. Further information on this 
field can be found in Internal Design. 
Equal to TOPM + NHIST 



.y/' 



Top margin 10 TOPM or zero 

Bottom margin 1 1 BOTM, or X ' FF ' if unspecified 

Left margin 12 LEFTM or zero 

Page size 13 Equal to X ' 00 ' if unspecified 

Line size 14-15 Equal to X ' 7FFF ' if unspecified 

Current line 16 Initialized to TOPM + NHIST 

Current indent 17 Initiahzed to left margin 

Buffer address 18-19 Zero if unspecified 



$IMAGE Subroutines 



You can create, save, and modify formatted screen images in disk and diskette data 
sets using the $IMAGE utility. The formatted screen subroutines retrieve and 
display these images. The $IMAGE subroutines provide support for any of the 
following: 

4978 terminals 

4979 terminals 

4980 terminals 

3101 terminals in block mode 
3161 terminals in block mode 
3151 terminals in block mode 

3 1 63 terminals in block mode 

3164 terminals in block mode. 

You can also use screen images created on a 4978, 4979, or 4980 on any of the 
terminals listed above by calling subroutines described in this appendix. Refer to the 
$IMAGE description in the Operator Commands and Utilities Reference for 
information on creating or exchanging terminal screen images for various terminals. 
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The SIMAGE subroutines perform screen formatting and input/output operations 
independent of the type of terminal upon which the appHcation runs. The 
orientation is towards writing/reading all unprotected fields with one operation. In 
this context the data in unprotected fields is of primary concern. 

Static screen appHcations use the SIMOPEN, $IMDTYPE, $UNPACK, $IMGEN, 
$IMGEN49, $IMGEN31, $IMGEN3X, and $IMC0N31 subroutine packages to 
process static screens defined using the $IMAGE utihty. 

SIMDTYPE is required for all static screen apphcations. In addition, the 
SIMOPEN and SUNPACK subroutines are also required, plus one of the following: 

• $IMGEN to intermix 4978, 3101, 3151, 3161, 3163, or 3164 screen images and 
to display these images on a 4978, 4979, 4980, 3101, 3151, 3161, 3163, or 3164 
terminal. Special screen images can be displayed only on the same terminal 
type. 

• $IMGEN3X to intermix both 3101 and 4978 images and to display those images 
on a 3101 terminal. 

• $IMGEN49 for 4978 images and to display those images on a 4978 or 4979 
terminal. 

• $IMGEN31 for 3101 images and to display those images on a 3101 terminal. 

If you wish to display 3101 images saved prior to EDX version 5.2 on a 3161, 3163, 
or 3164 terminal, you can: 

1. use the $IMAGE EDIT and SAVE commands to convert the 3101 image to the 
new format or 

2. code "3101" for the type operand in the CALL $IMOPEN instruction and 
include $IMCON3 1 when Unking your application program. 

During hnk-edit the $IMxxxx subroutines are included with your apphcation 
through the use of the autocall library. Normally $IMGEN is included. If you 
want one of the alternate ($IMGENxx) routines, exphcitly INCLUDE that module. 

For formatted screen images presented on a 3101, storage requirements and internal 
conversion time is reduced when you select only subroutine support that processes 
3101 images. 

You must code an EXTRN statement for each subroutine name to which your 
program refers. You must also hnk-edit the subroutines with your apphcation 
program. Specify $AUTO,ASMLIB as the autocall hbrary to include the screen 
formatting subroutines. See Chapter 5, "Preparing an Object Module for 
Execution" for details on the AUTOCALL feature of $EDXLINK. 

You call the formatted screen subroutines using the CALL instruction. The 
following section shows the CALL instruction syntax for each subroutine. Where an 
address argument is required by the subroutine, the label of the variable enclosed in 
parentheses causes the address of the variable to be passed (refer to the CALL 
instruction in the Language Reference). 

If an error occurs, the terminal I/O return code is in the second word of the task 
control block (TCB). These errors can come from instructions such as PRINTEXT, 
READTEXT, and TERMCTRL. 



^httmitfl*^ 
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$IMOPEN Subroutine 

The $IMOPEN subroutine reads the formatted screen image from disk or diskette 
into your program buffer. You can also perform this operation by using the 
DSOPEN subroutine or defining the data set at program load time, and issuing the 
disk READ instruction. See the section "Screen Image Buffer Sizes" on page C-12 
for a description of buffer sizes. SIMOPEN updates the index word of the buffer 
with the number of actual bytes read. To refer to the index word, code buffer -4. 



Users of EDX Version 5.2 and subsequent releases 

If you want to read images from disk or diskette using the DSOPEN subroutine 
instead of SIMOPEN and the images were saved prior to EDX Version 5.2, code the 
first 3 words of the buffer as follows: 

word 1: CI M" 
word 2: C'A G' 

word 3: xxxx, where xxxx is the address in the buffer 
which stores the 31xx terminal format 
or 00Q0, if the Slxx terminal format is not used 

The SIMAGE screen is read in at BUFFER + 6. 

Note: To use SIMOPEN, you must code an EXTRN statement in your program. 
You must also link-edit the program with SEDXLINK and specify an autocall to 
SAUTO,ASMLIB. 






Syntax: 



label 


CALL $IMOPEN,(dsname),(buffer),(type), 




P2 = ,P3 = ,P4 = 


Required: 


dsname,buffer 


Defaults: 


type = C'4978' 


Indexable: 


none 



Operands Description 

dsname The label of a TEXT statement that contains the name of the screen 

image data set. You can include a volume label, separated from the 
data set name by a comma. 

buffer The label of a BUFFER statement that defines the storage area into 

which the image data will be read. Allocate the storage in bytes, as in 
the following example: 

label BUFFER 1024, BYTES 
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type The label of a DATA statement that reserves a 4-byte area of storage 

and specifies the type of image data set to be read. The DATA 
statement must be on a full word boundary. Specify one of the 
following types: 

C'4978' The system reads an image data set for a 4978 terminal 

with a 4978/4979/4980 terminal format. This is the default 
terminal format. 

C'3101' The system reads an image data set for a 3101 terminal 
with a 31xx terminal format. 

C ' 3151 ' The system reads an image data set for a 3151 terminal 

C'3161' The system reads an image data set for a 3161 terminal 
with a 31xx terminal format. 

C'3163' The system reads an image data set for a 3163 terminal 
with a 3 Ixx terminal format. 

C'3164' The system reads an image data set for a 3164 terminal 
with a 3 Ixx terminal format. 

Note: The 3 Ixx terminal format is the format used for a 
3101, 3151, 3161, 3163, or 3164 terminal. 

C ' ' The system reads an image data set whose format 

corresponds with the type of terminal enqueued. If neither 
a 4978, 4979, 4980, 3101, 3151, 3161, 3163, or 3164 is 
enqueued (ENQT), the system assumes the default 4978 
image format. 

If you use this option, $IMOPEN will try to use the screen 
image that corresponds with the device. If that is not 
available, $IMOPEN will use a 4978/4979/4980 screen 
image. This is the default condition when you do not code 
this parameter. For example, if you are enqueued on a 
3151 or 3161 terminal, $IMOPEN will attempt to open a 
3 Ixx screen image. If it does not exist, SIMOPEN will use 
the 4978/4979/4980 screen image. 

Px = Parameter naming operands. Refer to the CALL instruction and 

Chapter 1 in the Language Reference. 

The following is an example of SIMOPEN: 

CALL SIMOPEN, (IMGDS) , (IMGBUFF) , (IMGTYP) 



IMGDS TEXT ' IMGDS,MYVOL' 

IMGBUFF BUFFER 1024, BYTES 
IMGTYP DATA C'3101' 



C-6 SC34-0943 



Static Screens and Device Considerations 



$IMOPEN Return Codes 

The following are the return codes from the $IMOPEN subroutine. The return 
codes are placed in the second word of the task control block (TCB) of the program 
or task calling the subroutine. The label of the TCB is the label of your program or 
task (taskname). Look at taskname + 2. 



Code 


Condition 


-1 


Successful completion 


1 


Disk I/O error 


2 


Buffer too small for 3101, 3151, 3161, 3163, or 3164 terminal 
information (31xx screen image) 


3 


Data set not found 


4 


Incorrect header or data set length 


5 


Input buffer too small 


6 


Invalid volume name 


7 


No 3101 image available 


8 


Data set name longer than eight bytes 



SIMDEFN Subroutine 

The SIMDEFN subroutine creates an lOCB for the formatted screen image. You 
can code the lOCB directly, but the use of SIMDEFN allows the image dimensions 
to be modified with the SIMAGE utihty without requiring a change to the 
application program. SIMDEFN updates the lOCB to reflect OVFLINE^YES. 
Refer to the TERMINAL configuration statement in the Installation and System 
Generation Guide for a description of the OVFLINE parameter. 



o 



Once you define an lOCB for the static screen, the program can then acquire that 
screen through ENQT. Once the screen has been acquired, the program can call the 
SIMPROT subroutine to display the image and the SIMDATA subroutine to display 
the initial unprotected fields. 

Note: To use SIMDEFN, you must code an EXTRN statement in your program. 
You must also fink-edit the program with SEDXLINK and specify an autocall to 
SAUTO,ASMLIB. 

Syntax: 



label 


CALL $IMDEFN,(iocb),(buffer),topm,leftm, 




P2 = ,P3 = ,P4-,P5 = 


Required: 


iocb,buffer 


Defaults: 


topm = 0,leftm = 


Indexable: 


none 
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Operands Description 

iocb The label of an lOCB statement defining a static screen. The lOCB 

need not specify the TOPM, BOTM, LEFTM nor RIGHTM 
parameters; these are "filled in" by the subroutine. The following 
IOCB statement would normally suffice: 



label IOCB terminal ,SCREEN=STATIC 

buffer The label of an area containing the screen image in disk storage 

format. The format is described in the section "Screen Image Buffer 
Sizes" on page C-12. 

topm Indicates the screen position at which line will appear. If its value is 

such that Unes would be lost at the bottom of the screen, then it is 
forced to zero. This parameter must equal zero for all 3101, 3151, 
3161, 3163, or 3164 terminal applications. The default is also zero. 

leftm Indicates the screen position at which the left edge of the image will 

appear. If its value is such that characters would be lost at the right 
edge of the screen, then it is forced to zero. This parameter must 
equal zero for all 3101, 3151, 3161, 3163, or 3164 terminal 
apphcations. The default is also zero. 

Px = Parameter naming operands. Refer to the CALL instruction and 

Chapter 1 in the Language Reference. 



The following is an example of SIMDEFN: 

CALL SIMDEFN, (IMGIOCB) , (IMGBUFF) ,0,0 



\J 



ENQT IMGIOCB 



PROGSTOP 
IMGIOCB IOCB SCREEN=STATIC 
IMGBUFF BUFFER 1024, BYTES 

SIMPROT Subroutine 

The SIMPROT subroutine uses an image created by the $IMAGE utihty to prepare 
the defined protected and blank unprotected fields for display. At the option of the 
calling program, a field table can be constructed. The field table gives the location 
(LINE and SPACES) and length of each unprotected field. 

Upon return from SIMPROT, your program can force the protected fields to be 
displayed by issuing a TERMCTRL DISPLAY. This is not required if a call to 
SIMDATA follows because SIMDATA forces the display of screen data. 

All or portions of the screen may be protected after SIMPROT executes. Because 
the operator cannot key data into protected fields, subsequent read instructions (such 
as QUESTION, GETVALUE and READTEXT) should be directed to unprotected 
areas of the screen, or the protected areas should be erased. 
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Notes: 

1 . To use SIMPROT, you must code an EXTRN statement in your program. You 
must also link-edit the program with $EDXLINK and specify an autocall to 
$AUTO,ASMLIB. 

2. Do not call both SIMPROT and SIMDATA by separate tasks to operate 
simultaneously. Problems will occur because both call the $IMDTYPE 
subroutine. 

Syntax: 



label 

Required: 
Defaults: 
Indexable: 


CALL $IMPROT,(buffer),(ftab),P2 = ,P3 = 

buffer,ftab (see note) 

none 

none 






Operands Description 

buffer The label of an area containing the screen image in disk storage 

format. The format is described in the section "Screen Image Buffer 
Sizes" on page C-12. 

ftab The label of a field table constructed by SIMPROT giving the location 

(lines, spaces) and size (characters) of each unprotected data field of 
the image. 

Note: The ftab operand is required only if the application executes on 
a 3101, 3151, 3161, 3163, or 3164 terminal in block mode, or if a user 
buffer is used in SIMDATA. 

Px = Parameter naming operands. Refer to the CALL instruction and 

Chapter 1 in the Language Reference. 



The field table has the following form: 



label-4 
(one word) 



number of fields label-2 number of words label line * FIELD 1 



spaces 
size 
spaces 
size 



(one word) 
(one word) label + 6 line * FIELD 2 



label + 6(n-l) 



Hne * FIELD n 

spaces 

size 
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The field numbers correspond to the following ordering: left to right in the top line, 
left to right in the second line, and so on to the last field in the last hne. Storage for 
the field table should be allocated with a BUFFER statement specifying the desired 
number of words using the WORDS parameter. The buffer control word at label - 2 
will be used to Hmit the amount of field information stored, and the buffer index 
word at buffer — 4 is set with the number of fields for which information was stored, 
the total number of words being three times that value. If the field table is not 
desired, code zero for this parameter. 

The following is an example of SIMPROT: 



CALL SIMPROT, (IMGBUFF),(FTAB) 
PRINTEXT LINE=FTAB,SPACES=FTAB+2 
READTEXT INPUT, LINE=FTAB,SPACES=FTAB+2 



POSITION CURSOR 
OPERATOR INPUT 



IMGBUFF BUFFER 
FTAB BUFFER 
INPUT TEXT 



1024, BYTES 
128, WORDS 
LENGTH=20 



SIMPROT Return Codes 

The following are the return codes from the SIMPROT subroutine. The return 
codes are placed in the second word of the task control block (TCB) of the program 
or task calling the subroutine. The label of the TCB is the label of your program or 
task (taskname). Look at taskname + 2. 






Code 


Condition 


-1 


Successful completion 


9 


Invahd format in buffer 


10 


Ftab truncated due to insufficient buffer size 


11 


Error in building ftab from 31xx terminal format; partial ftab 
created 


12 


Invalid terminal type 



$IMDATA Subroutine 

$IMDATA displays the initial data values for an image which is in disk storage 
format. Use SIMDATA: 

• To display the unprotected data associated with a screen image, if the content of 
the buffer is a screen format retrieved with SIMOPEN. 

• To "scatter write" the contents of a user buffer to the input fields of a displayed 
screen image. 

Note: You must call SIMDATA if any of your unprotected fields have the right 
justify or must enter characteristics. 
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If the buffer is retrieved with $IMOPEN, the buffer begins with either the characters 
"IMAG," or "IM31," and the buffer index (buffer — 4) equals the data length 
excluding the characters "IMxx." 

You can specify a user buffer containing appHcation-generated data. Set the first 
four bytes of the buffer to USER and set the buffer index (buffer — 4) to the data 
length excluding the characters USER. 

All or portions of the screen may be protected after $IMDATA executes. Because 
the operator cannot key data into protected fields, subsequent read instructions (such 
as QUESTION, GETVALUE and READTEXT) should be directed to unprotected 
areas of the screen, or the protected areas should be erased. 

Notes: 

1 . To use $IMDATA;"you must code an EXTRN statement in your program. You 
must also link-edit the program with SEDXLINK and specify an autocall to 
$AUTO,ASMLIB. 

2. Do not call both $IMDATA and SIMPROT by separate tasks to operate 
simultaneously. Problems occur because both call the $IMDTYPE subroutine. 

Syntax: 



^*>, 



label 


CALL $IMDATA,(buffer),(ftab),P2 = ,P3 = 


Required: 


buffer,ftab (see note) 


Defaults: 


none 


Indexable: 


none 



Operands Description 

buffer The label of an area containing the image in disk-storage format. 

ftab The label of a field table constructed by SIMPROT giving the location 

(hnes,spaces) and size (characters) of each unprotected data field of the 
image. 

Note: The ftab operand is required only if the application executes on 
a 3101, 3151, 3161, 3163, or 3164 terminal in block mode, or if a user 
buffer is used in SIMDATA. 

Px = Parameter naming operands. Refer to the CALL instruction and 

Chapter 1 in the Language Reference. 

The following is an example of $IMDATA: 



CALL $IMDATA,(IMGBUFF),(FTAB) 
PRINTEXT LINE=FTAB,SPACES=FTAB+2 



POSITION CURSOR 



IMGBUFF BUFFER 
FTAB BUFFER 



1024, BYTES 
300, WORDS 
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$IMDATA Return Codes 

The following are the return codes returned from the $IMDATA subroutine. The 
return codes are returned in the second word of the task control block (TCB) of the 
program or task calling the subroutine. The label of the TCB is the label of your 
program or task (taskname). Look at taskname + 2. 



Code 


Condition 


-1 


Successful completion 


9 


Invalid format in buffer 


12 


Invahd terminal type 



Screen Image Buffer Sizes 



Under normal circumstances, the size of the disk buffer can vary between 256 and 
3096 bytes. Because data compression is used in storing the images, many images 
will require only 512 bytes, and 1024 bytes will be adequate for typical applications 
using a 4978/4979/4980 image. 3101, 3151, 3161, 31 63 and, 3164 terminal data 
stream images (31xx screen images) are much larger. 

The SIMAGE utihty tells you the required buffer sizes for the 4978, 4979, 4980, 
3101, 3151, 3161, 3163, and 3164 buffers. If your application program will run on 
any type of terminal, use the largest of the buffer sizes. 



The display subroutines normally write images to the terminal in line-by-line fashion. 
Performance can be improved by providing a terminal buffer large enough to 
contain multiple hues. Since the display subroutines perform concatenated write 
operations whenever possible, using a larger buffer results in fewer such operations 
and, therefore, faster generation of the display image. 






For example, for a full screen image (24 x 80), a time versus space trade-off can be 
made by choosing a buffer size that is a multiple of 80 bytes (1 line), up to a 
maximum of 1920 bytes. A temporary buffer can be defined by coding the 
BUFFER = parameter, on the lOCB which is used to access the screen. This buffer 
should be unique and should not be confused with disk image buffer. 



o 
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Example of Using $IMAGE Subroutines 

The following program shows the SIMAGE subroutines in a general application 
program. Under direction of the terminal operator, this program displays on a 4978, 
4979, 3101, 3151, 3161, 3163, or 3164 terminal any image stored on disk. For each 
image, a field table (ftab) is constructed and used to modify initial data values. 

In this example, use of the field size from the field table is for illustrative purposes 
only. Each unprotected output operation is terminated by the beginning of the next 
protected field, unless MODE = LINE is coded. 

Additional examples on the use of the SIMAGE subroutines are in the appendix of 
the Language Reference. 

IMDISP PROGRAM BEGIN 

EXTRN $IMOPEN,$IMDEFN,$IMPROT,$IMDATA 
* 

* GET TERMINAL NAME FOR SCREEN PRINTOUT 

* 

BEGIN READTEXT IMAGE, 'TERMINAL: ' 

* 

* GET IMAGE DATA SET NAME 

* 

READTEXT DSNAME, 'DATA SET: ' ,PROMPT=COND 

* 

* OPEN IMAGE DATA SET (4978 SCREEN IMAGE) 

* 

CALL $IMOPEN, (DSNAME), (DISKBFR) 
TCBGET CODE,$TCBC02 * SAVE RETURN CODE 
IF C0DE,NE,-1 * CHECK RETURN CODE FOR ERRORS 
PRINTEXT '@OPEN ERROR CODE' 
PRINTNUM CODE * PRINT ERROR CODE 
GOTO NEXT * ASK IF TRY AGAIN 
ENDIF 
* 

* CONSTRUCT lOCB 

* 

CALL SIMDEFN, (IMAGE) , (DISKBFR) ,0,0 

ENQT IMAGE * ACQUIRE STATIC SCREEN 

TERMCTRL BLANK * BLANK SCREEN 

* * WRITE PROTECTED FIELDS 

* * AND BUILD FIELD TABLE 

* * AT FTAB 
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DISPLAY PROTECTED FIELD DATA ON 
TERMINAL SCREEN 



CALL 



$IMPROT,(DISKBFR),(FTAB) 



DISPLAY DEFAULT DATA ON 
TERMINAL SCREEN 



NEXT 



DSNAME 



CALL $IMDATA,(DISKBFR),(FTAB) 

* SET CURSOR AT 1ST FIELD 



PRINTEXT 


LINE=FTAB,SPACES= 


fTAB+2 


TERMCTRL 


DISPLAY 


* 


UNBLANK SCREEN 


DEQT 




* 


RETURN TO THIS TERMINAL 


WAIT 


KEY 


* 


WAIT FOR OPERATOR 


ENQT 


IMAGE 


* 


BACK TO TARGET TERMINAL 


TERMCTRL 


BLANK 


* 


BLANK SCREEN 



DISPLAY #'S IN DATA FIELDS 



ENQT 

CALL 

DEQT 

WAIT 

ENQT 

ERASE 

DEQT 

QUESTION 

PROGSTOP 

TEXT 



IMAGE * ACQUIRE STATIC SCREEN 
$IMDATA,(REPBFR),(FTAB) 

KEY * ALLOW VIEWING TIME 

IMAGE * ACQUIRE STATIC SCREEN 
LINE=0,MODE=SCREEN,TYPE=ALL * ERASE 
* BACK TO ROLL SCREEN 
'ANOTHER IMAGE? ' ,YES=BEGIN 



LENGTH=16 



* DATA SET NAME 



1$ 



y 



BUILD A BUFFER OF #'S FOR A SECOND DATA 
FIELD DISPLAY 



Bl 
B2 
REPBFR 



DISKBFR 

IMAGE 
CODE 
FTAB 
LINE 



DC 

DC 

DC 

DC 

DC 

BUFFER 

DC 

lOCB 

DC 

BUFFER 

TEXT 

ENDPROG 

END 



F'72' * Bl AND B2 INDEX REPBFR 
F'76' * THAT HIGHLIGHTS THE DATA 
C'USER' * FIELDS FOR USER 

C ■ #################################### ' 
C ' #################################### ' 



1064, BYTES 

X'0808' 

SCREEN=STATIC 

F'O' 

300 

LENGTH=80 



DISK BUFFER 
TEXT CONTROL FOR NAME 
lOCB FOR IMAGE 
RETURN CODE 
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$UNPACK and $PACK Subroutines 

The SUNPACK and $PACK subroutines move and translate 
compressed/noncompressed byte strings. These subroutines are used internally by 
the $IMPROT and $IMDATA subroutines as well as by the SIMAGE utiUty. 
However, they can also be called directly by an application program. 

The program preparation needed for applications calling SUNPACK and $PACK is 
similar to that needed for the SIMAGE subroutines. An EXTRN statement is 
required in the application and the autocall to $AUTO,ASMLIB is required in the 
hnk-control data set (input to $EDXLINK). 

$UNPACK Subroutine 

This subroutine moves a series of compressed and noncompressed byte strings and 
translates the byte strings to noncompressed form. 

Syntax: 



label 


CALL 


$UNPACK,source,dest,P2 = 


,P3 = 


Required: 


source,dest 






Defaults: 


none 






Indexable: 


none 







Operands Description 

source The label of a fullword containing the address of a compressed byte 

string. (See Figure C-1 for the compressed format.) At completion of 
the operation, this parameter is increased by the length of the 
compressed string. 

dest The label of a fullword containing the address at which the expanded 

string is to be placed. The length of the expanded string is placed in 
the byte preceding this location. The SUNPACK subroutine can, 
therefore, conveniently be used to move and expand a compressed byte 
string into a TEXT buffer. 



F^ 


F2 


e • e 


Fn 


X'OO' 



Each F\.. Fn is either: 



L 


C^ 


C2 


s e « 


Cn 



or 



( L is greater than zero and represents 
the length of chars ( C ) that follow ) 



L C 



( L is less than zero and represents 
L repetitions of C ) 



L and C are one byte in length. 
Figure C-1. Compressed Data Format 



BG0712 
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The following example shows how to unpack the compressed protected data of a 
$IMAGE screen format. 



MOVEA 
MOVEA 

MOVE 

MOVE 

DO 
CALL 
MOVE 

ADD 
ENDDO 



#1,0UTAREA 
CP0INTER,CBUF+12 



POINT TO EXPAND BUFFER 
POINT TO FIRST BYTE OF 

COMPRESSED DATA 
INIT DO LOOP CTR 
INIT MOVE LENGTH CODE 



LINECNT,CBUF+4 

M0VELNG,CBUF+6 

LINECNT 

$UNPACK,CPOINTER, STRGPTR UNPACK COMPRESSED DATA 

(0,#1) , STRING, (0,BYTE) ,P3=M0VELNG MOVE 

UNPACKED DATA 
#1,M0VELNG 



OUTAREA 

* 


DATA 


CL1920' ■ 


CPOINTER 


DATA 


A'O' 


LINECNT 


DATA 


F'O' 


STRGPTR 

* 


DATA 


A(STRING) 


STRING 


TEXT 


LENGTH=80 


CBUF 


BUFFER 


1000, WORDS 



WILL CONTAIN ALL OF THE 

UNPACKED DATA 
POINTER TO COMPRESSED DATA 
NBR OF FORMAT LINES TO UNPACK 
ADDR OF TEMP LOCATION TO 

RECEIVE UNPACKED DATA 
TEMP LOCATION TO RECEIVE 

UNPACKED DATA 
CONTAINS $ IMAGE FORMAT 

WITH PACKED DATA 






$PACK Subroutine 

This subroutine moves a byte string and translates it to compressed form. 
Syntax: 



label 


CALL 


$PACK,source,dest,P2 = ,P3 = 


Required: 


source,dest 




Defaults: 


none 




Indexable: 


none 





Operands Description 

source The label of a fullword containing the address of the string to be 

compressed. The length of the string is taken from the byte preceding 
this location, and the string could, therefore, be the contents of a 
TEXT buffer. 

dest The label of a fullword containing the address at which the compressed 

string is to be stored. At completion of the operation, this parameter 
is incremented by the length of the compressed string. 
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Special Characters 

$$EDXIT task error exit routine 

description 7-16 

output example 7-17 

using 7-17 
SDEBUG utility 

change 

storage 7-1 

commands 7-4 

description 7-1 

display 

unmapped storage 7-9 

ending 7-9 

finding errors 7-6 

list 

registers 7-1 
storage location 7-6 

loading 7-3 

patching a program 7-7 

restarting a program 7-1 

set 

breakpoints 7-5 
trace ranges 7-1 
SDISKUTl utility 

allocating data set for compiler 4-1 

allocating object data set 1-13 
$DISKUT3 program 

allocate a data set with extents 10-4 

allocating a data set 10-2 

delete a data set with extents 10-7 

deleting a data set 10-7 

description 10-1 

opening a data set 10-6 

performing more than one operation 10-12 

releasing unused space 10-8 

renaming a data set 10-9 

setting end-of-data 10-10 
SEDXASM Event Driven Language compiler 

checking the Hsting 1-16 

correcting compiler errors 4-7 

description 4-1 

hsting example 4-11 

overview 4-1 

parameter input menu 1-14 
SEDXLINK utility 

autocall feature 5-8 

control statements 5-3 
AUTOCALL 5-8 
INCLUDE 5-5 
LINK 5-6 
OVERLAY 5-7 

creating a load module 1-17 

creating overlay segments 9-12 



SEDXLINK utiHty (continued) 

link editing a single object module 5-1 

link editing more than one object module 5-4 

load using 

$L interactive 5-2 
$L noninteractive 5-9 

overview 5-1 

parameter input menu 1-18 

primary-control-statement data set 
example 5-9 

required for PUTEDIT 5-8 
SFSEDIT utility 

creating primary control data set 5-9 

overview 3-1 
$IMAGE utihty 

create a screen C-3 

description C-3 

example C- 1 3 

use for device independence 8-28 
SIMDATA subroutine 

description C-10 

example 8-29, C- 11, C- 13 

return codes C-12 
SIMDEFN subroutine 

description C-7 

example C-8, C-13 
$IMOPEN subroutine 

description C-5 

example 8-28, C-6, C-13 

reading a screen image 8-18 

return codes C-7 
SIMPROT subroutine 

description C-8 

example 8-28, C-10, C-13 

return codes C-10 
SJOBUTIL UtiHty 

submitting a program from a program 6-5, 6-6 
SMSGUTl UtiHty 

examples 17-5 

format messages 17-4 

store messages 17-4 
$PACK subroutine 

description C-16 
SPREFIND utility 

overview 5-10 
$SMM02 secondary option menu 1-11 
SSUBMITP program 

example 6-5 

sample job stream processor commands 6-6 

submitting a program from a program 6-5 
SSYSCOM system common data area 

accessing through a program 20-1 

sample programs 20-1 
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STAPEUTl utility 
change 

label processing attributes 11-8 
SUNPACK subroutine 
description C-15 
example C-16 
$VARYON - set device online 

processing a tape containing more than one data 
set 11-5 

A 

A/I 

See analog input 
A/O 

See analog output 
ACCA 

diagnosing errors 7-15 
access $SYSCOM through a program 20-1 
add 

consecutive integers 2-17 

double-precision integers 2-16 

extended-precision floating point 2-21 

floating point 2-21 

integer data 2-16 

records to a tape file 11-11 
ADD instruction 

adding consecutive integers 2-17 

adding double-precision integers 2-16 

adding integer data 2-16 

coding example 2-16 
advance input B-3 
AI 

See analog input 
allocate 

data set 

for compiler 4-1 
for object code 1-12 
from a program 10-2 
with extents 10-4 
alphanumeric data 

reading 2-9 

writing 2-29 
analog input 

description 14-1 

example 14-8 

lODEF statement 14-4 

sample 14-11, 14-12 

SBIO instruction 14-7 
analog output 

description 14-1 

lODEF statement 14-4 

SBIO instruction 14-7 
AND instruction 

comparing bit strings 2-27 
arithmetic 

comparison 2-31 

operations 2-16 



arithmetic (continued) 

values, defining 2-3, 2-4 
ASCII terminal 

used in graphics application 15-1 
assign 

sensor I/O addresses 14-3 
ATTACH instruction 

synchronizing tasks 9-6 
attention key B-1 
ATTNLIST statement 

use in terminal support B-3 
attribute characters, 3101 8-25, 8-32 
autocall feature 

example 5-8 

including task error exit routine 7-17 

loading 5-8 

with static screen program 8-21 

B 

background job, submitting 6-2 
binary 

converting to 2-12 

to EBCDIC 2-11 
blanks, defining 2-4 
blinking field 8-38 
branch 

to another location 2-34 
breakpoint and trace range 

settings 7-5 
buffer 

contents of 2-6 

defining 2-6 

index 2-6 
BUFFER statement 

coding 2-6 
bypassing standard labels, tape 1 1 -4 

c 

CALL instruction 

calling a subroutine 9-8 

loading an overlay segment 9-12 

overview 9-6 
change 

attribute byte 8-39 

line of data set 3-5 

screen attribute 8-35 

storage locations 7-1 
character string 

converting to 2-11 

defining 2-4 
close 

standard-label tape 11-4 
code 

a program 1-2 

reentrant routine 19-1 
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comparing bit-strings 

AND instruction 2-27 

exclusive-OR 2-24 

inclusive-OR 2-25 
comparing storage 

arithmetically 2-3 1 

logically 2-32 
compile 

a program 1-11, 4-1 
compiler 

See SEDXASM Event Driven Language compiler 
compiler errors, correcting 4-7 
compressed byte string C-16 
CONCAT instruction 

overview 15-1 
continuation line 1-2 
CONTROL instruction 

closing a standard-label tape 11-4 
conventions, data set 6-3 
convert 

checking for conversion errors 2-15 

data 2-11 

floating point to integer 2-14 

integer to floating point 2-14 

source messages 17-4 

to binary 2-12 

to EBCDIC 2-11 

4978 screens 8-31 
CONVTB instruction 

converting to EBCDIC 2-1 1 
CONVTD instruction 

converting to binary 2-12 
create 

a screen using $IMAGE C-3 

data entry field 8-40 

data set for program messages 17-1 

load module 1-17 

source data set 3-2 

static screen 8-16 

unprotected fields 8-37 
cross-partition services 

finding a program 1 2-4 

introduction 12-1 

loading a program 12-2 

moving data across partitions 12-10 

reading data across partitions 12-12 

sharing resources 12-6 

starting a task 12-4 

synchronizing tasks 12-8 



D 

D/I 

See digital input 
D/O 

See digital output 
data 

adding 2-16 

alphanumeric, reading 2-9 

alphanumeric, writing 2-29 

comparing 2-3 1 

converting 2-11 

defining 1-3 

logical 2-24 

manipulating 2-16 

manipulating floafing point 2-21 

manipulating logical 2-24 

moving 2-10 

moving across partitions 12-10 

numeric, reading 2-9 

numeric, writing 2-30 

processing 1 -4 

reading 

across partitions 12-12 

from a static screen 8-8 

from disk/diskette 2-7 

from tape 2-8 

from terminal 2-8 
retrieving 1-3 
writing 

to disk/diskette 2-28 

to static screen 8-8 

to tape 2-29 

to terminal 2-29 
data management from a program 10-1 
data set 
allocate 

for compiler 4-1 

from a program 10-2 

with $DISKUT3 10-1 

with extents 10-4 
creating 3-2 
delete 

from a program 10-7 
entering a program into 1 -6 
format 6-3 

identifying in a program 2-2 
locating before loading a program 5-10 
modifying 3-5 
name, defined 6-3 
naming conventions 6-3 
open from a program 10-6 
release unused space 10-8 
rename from program 10-9 
saving 3-4 

saving screen image 8-15 
set end-of-data 10-10 
specifying 6-3 
volume, defined 6-3 
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data set control block (DSCB) 

allocating a data set from a program 10-2 

opening a data set from a program 10-6 
data set extents 

allocate data set with 10-4 

delete data set with 10-7 
DATA statement 

assigning an initial value 2-3 

character strings, defining 2-4 

defining a doubleword 2-3 

defining a halfword 2-3 

defining floating point 2-4 

duplication factor 2-3 

reading from static screen 8-20 

reserving storage for integers 2-3 

writing to static screen 8-20 
data storage area, coding 2-6 
DC statement 

defining character strings 2-4 

defining floating point 2-4 

reserving storage for integers 2-3 
debugging utility 

See SDEBUG utility 
decimal arithmetic operations 2-16 
define 

character strings 2-4 

data 1-3, 2-2 

floating-point values 2-4 

input/output area 2-6 

location of message data set 17-6 

primary task 2-1 

static screen 8-6 

subroutine 9-7 

TEXT statement 2-6 

virtual terminals 13-1 
definition statement format 2-2 
delete 

data set 

from a program 10-7 
with extents 10-7 

line from data set 3-7 

more than one hne 3-8 
design 

a program 1-1 
DETACH instruction 

synchronizing tasks 9-6 
device independence 

between 4978, 4979, or 4980 and 3101 8-24 

coding EDL instructions 8-26 

for static screens 8-24 

using the SIMAGE subroutines 8-28 
device type, finding 10-24 
DI 

See digital input 
digital input 

description 14-1 

example 14-9, 14-15 

lODEF statement 14-4 



digital input (continued) 

SBIO instruction 14-7 
digital output 

description 14-1 

example 14-9 

lODEF statement 14-4 

SBIO instruction 14-7 
directory member entry (DME) 

updated by SETEOD 10-21 
display 

protected data 8-28 

unmapped storage 7-9 

unprotected data 8-28 
display screen 

reading data from 8-1 

writing data to 8-1 
divide 

accessing the remainder 2-20 

consecutive integers 2-20 

double-precision integers 2-20 

extended-precision floating point 2-24 

floating-point numbers 2-23 

integers 2-19 
DIVIDE instruction 

accessing the remainder 2-20 

dividing consecutive integers 2-20 

dividing double-precision integers 2-20 

dividing integers 2-19 
DO 

See digital output 
DO instruction 

DO UNTIL 2-33 

DO WHILE 2-33 

executing code repetitively 2-32 

nested DO loop 2-33 

nested IF instruction 2-34 

overview 2-30 

simple DO 2-32 
DSOPEN subroutine 

considerations 10-15 

description 10-14 

error exits 10-14 

example 10-16 
duplication factor 2-4 
dynamic data set extents 

allocate a data set with 10-2 

delete a data set with 10-7 

E 

EBCDIC 

converting to 2-11 
EBCDIC-to-binary conversion 2-12 
EDL programming 

basic functions 2-1 

coding 1-2 

compiling 1-11, 4-1 

correcting compiler errors 4-7 
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EDL programming (continued) 

creating a load module 1-17 

designing 1-1 

entering 1-6 

executing 1-20, 6-1 

running 1-20, 6-1 
EDX record, defined 2-7 
ELSE instruction 

overview 2-30 
end 

a program 1-5, 2-35 
end-of-file, indicating with SETEOD 10-21 
END statement 

overview 2-35 
ENDDO instruction 

overview 2-30 
ENDIF instruction 

overview 2-30 
ENDPROG statement 

overview 2-35 
ENQT instruction 

getting exclusive access to a terminal 8-18 

use with logical screens C-2 

use with static screen 8-7 
enqueue 

static screen 8-35 
enter 

advance input B-3 

program into a data set 1-6 
EOR instruction 

comparing bit strings 2-24 
EQ (equal) 2-30 
EQU statement 

coding 2-5 

coding example 2-5 

used to generate labels 2-35 
erase 

individual field 8-38 

static screen 8-7, 8-36 

to end of static screen 8-42 
ERASE instruction 

erasing a static screen 8-7, 8-36 

erasing an individual field 8-38 

erasing to end of static screen 8-42 
error codes 

See return codes 
error handling 

checking for conversion errors 2-15 

DSOPEN 10-14 

system-supplied 7-16 

task error exit 7-16 
errors 

compiler 4-7 

finding program 7-1 
Event Driven Language (EDL) 

See EDL programming 
exclusive-OR operation 2-24 



executable instruction, defined 2-1 
execute 

program 

with session manager 1-20, 6-1 
exit 

error (DSOPEN) 10-14 
extended-precision 

floating-point arithmetic 2-21 
extents 

allocate data set with 10-4 

delete data set with 10-7 
EXTRACT copy code routine 10-24 



FADD instruction 

adding extended-precision floating point 2-21 

adding floating point 2-21 
FDIVD instruction 

dividing extended-precision floating point 2-24 

dividing floating point 2-23 
field table (FTAB) 

SIMDATA subroutine C-11 

SIMPROT subroutine C-9 

format of C-9 
file 

See data set 
find 

device type 10-24 

logic errors in a program 7-6 

program 12-4 
FIRSTQ instruction 

retrieving data from a queue 1 8-2 
floating-point 

addition 2-21 

assigning an initial value 2-4 

converting integer to 2-14 

converting to binary 2-13 

converting to EBCDIC 2-1 1 

converting to integer 2-14 

defined 2-2 

defining 2-4 

defining more than one data area 2-4 

extended-precision 2-4 

in exponential notation 2-4 

manipulating 2-21 

requirements to use instructions 2-21 

single-precision 2-4 
FMULT instruction 

multiplying extended-precision floating point 2-23 

multiplying floating-point data 2-22 
formatted screen subroutines 

constructing an lOCB C-7 

display initial data values C-10 

preparing fields for display C-8 

reading the image C-5 
FPCONV instruction 

converting from floating point to integer 2-14 
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FPCONV instruction (continued) 

converting from integer to floating point 2-14 
FREESTG instruction 

releasing unmapped storage 9-15 
FSUB instruction 

subtracting extended-precision floating point 2-22 

subtracting floating-point data 2-22 
full-screen text editor (SFSEDIT) 3-1 



gather read operation 8-11, 8-26, 8-29 
GE (greater than or equal) 2-30 
GETSTG instruction 

obtaining unmapped storage 9-14 
GETVALUE instruction 

processing interrupts B-2 

reading numeric data 2-9 

retrieving prompts from a data set 17- 
GIN instruction 

coding description 15-1 

overview 15-1 
GOTO instruction 

overview 2-30 

transfer to another location 2-34 
graphics 

functions overview 15-1 

hardware considerations 15-1 

instructions 

CONCAT 15-1 
GIN 15-1 
PLOTGIN 15-1 
XYPLOT 15-2 
YTPLOT 15-2 

programming example 15-3 

requirements 15-1 
GT (greater than) 2-30 



H 

hexadecimal, defining 2-3 



I 

identify 

data sets in a program 2-2 
IF instruction 

comparing areas of storage 2-3 1 

overview 2-30 
image, formatted screen 

See screen 
INCLUDE control statement (SEDXLINK) 5-5 
inclusive-OR 2-25 
independence, volume 10-20 
index, part of standard buffer 2-6 
initial value, assigning 2-3 
initialize 

nonlabeled tape 11-9 



input 

area, defining 2-6 

reading from disk 2-7 

reading from diskette 2-7 

reading from tape 2-8 

reading from terminal 2-8 
input menu 

compiler 1-14 

linkage editor 1-18, 5-5 
input/output control block 

See lOCB instruction 
insert 

hne in data set 3-6 
integer 

adding 2-16 

assigning an initial value 2-3 

converting floating-point to 2-14 

converting to binary 2-12 

converting to EBCDIC 2-11 

converting to floating-point 2-14 

defined 2-2 

doubleword, defining 2-3 

halfword, defining 2-3 

manipulating 2-16 

reserving storage for 2-3 
interactive debugging 7-1 
interrupt 

servicing 

instructions B-2 
interrupt keys 

attention key B-1 

enter key B-2 

program function (PF) keys B-1 
interrupt status byte (ISB) 

diagnosing errors from ACCA device 
lOCB instruction 

defining logical screen C-2 

defining static screen 8-17 

structure C-3 
lODEF statement 

function 14-3 

SPECPI process interrupt user routine 
lOR instruction 

comparing bit strings 2-25 



ff 



7-15 



14-5 



J 

job 



submit 

background 6-2 
from a program 6-2 
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K 

keyword operand 
definition of 2-2 

L 

label 

definition 1-2 

generating 2-35 
labels, tape A-1 
LE (less than or equal) 2-30 
LINK control statement (SEDXLINK) 5-6 
link-edit 

a program 1-17 

a single object module 5-1 

creating segment overlay structure 9-12 

program that uses SIMAGE subroutines 5- 

required for GETEDIT 5-8 

static screen program 8-21 
linkage editor 

See $EDXLINK utility 
list 

registers 7-1 

storage location 7-6 
load 

programs 

from a program 12-2 

from a virtual terminal 13-2 

with the session manager 1-20, 6-1 

session manager 1-6 

text editor 3-1 
LOAD instruction 

submitting a job from a program 6-5 

used with overlays 9-13 
load module 

creating 1-17, 5-1 

executing 6- 1 
locate 

data set before loading a program 5-10 

logic errors in a program 7-1 
logical comparison 

AND instruction 2-27 

exclusive-OR instruction 2-24 

IF instruction 2-32 

inclusive-OR instruction 2-25 
logical end-of-file on disk 10-21 
logical screen 

examples C-1, C-2 

using lOCB and ENQT to define C-2 

using TERMINAL to define C-1 
logon menu, session manager 1-6 
loops 2-32 
LT (less than) 2-30 



M 

magnetic tape 

See tape 
manipulating data 2-16 
message 

defining 2-6 
MESSAGE instruction 

example 17-7 

retrieving a message from a data set 17-7 
messages, program 

coding 17-2 

creating 

coding variable fields 17-2 
data set for 17-1 

define location of message text 17-6 

formatting 1 7-4 

retrieving 17-6 

sample program 17-9 

sample source message data set 17-4 

storing 1 7-4 
modified data 

reading from the 3101 8-42 

3101 considerations 8-40 

3101 example 8-41 

3151 example 8-41 

3151, 3161, 3163, and 3164 considerations 8-40 

3161 example 8-41 

3163/3164 example 8-41 
modified data tag 8-40 
modify 

existing data set 3-5 
move 

data 2-10 

data across partitions 12-10 

lines in a data set 3-9 
MOVE instruction 

moving data 2-10 

moving data across partitions 12-10 
multiply 

consecutive integers 2-19 

double-precision integers 2-18 

extended-precision floating point 2-23 

floating point 2-22 

integers 2-18 
MULTIPLY instruction 

multiplying consecutive integers 2-19 

multiplying double-precision integers 2-18 

multiplying integers 2-18 
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N 

naming conventions, data set 6-3 
NE (not equal) 2-30 
NEXTQ instruction 

putting data into a queue 18-1 
noncompressed byte string C-15 
nondisplay field 8-37 
nonlabeled tapes 

defined 11-1 

defining 11-8 

initializing 1 1 -9 

reading 11-10 

writing 11-10 
numbers, defining 2-3, 2-4 
numeric data, reading 2-9 
numeric data, writing 2-30 



object code data set 1-11 
object module 

creating 4-1 

link editing 5-1, 5-4 
open 

data set 10-14 

data set from a program 10-6 
operand 

definition 1-2 
operation 

definition 1 -2 
option menu 

data management 1-12 

program preparation 1-13 

text editing 1-7 
output 

area, defining 2-6 

compiler 4-11 

printing spooled output 16-6 

writing to a terminal 2-29 

writing to disk 2-28 

writing to diskette 2-28 

writing to tape 2-29 
overlay 

area 9-12 

creating 9-12 

defined 9-9 

example 9-11 

overlay program 
defined 9-9 
described 9-12 

overlay segment 
link editing 5-7 
structure 9-10 

specifying 9-12 
OVERLAY control statement (SEDXLINK) 5-7 



parameter passing 

to a subroutine 9-7 
passing parameters 

using virtual terminals 13-2 
patch 

program 7-7 
PF keys 

See program function (PF) keys 
PI 

See process interrupt 
plot control block (graphics) 1 5-2 
PLOTCB control block 15-2 
PLOTGIN instruction 

overview 15-1 
POST instruction 

synchronizing tasks 9-6 

synchronizing tasks in other partitions 12-8 
precision 

floating-point arithmetic 2-21 
preparing object modules for execution 

link editing 5-1 

hnk editing more than one object module 5-4 

predefining data sets 5-10 
primary-control-statement data set 5-9 
primary option menu, session manager 

defined 1-7 
primary program 13-1 
primary task 

defined 2-1 
PRINTEXT instruction 

positioning the cursor 8-7, 8-19 

printing a message buffer 2-6 

prompting for data 8-7 

use in terminal support 

changing individual fields 8-27 
using on 3101 terminals 8-30 

writing to a roll screen 8-4 

writing to a static screen 8-8 

writing to a terminal 2-29 
PRINTNUM instruction 

writing numeric data to a terminal 2-30 

writing to a terminal 2-29 
priority 

assigned to tasks 9-1 
process interrupt 

description 14-1 

lODEF statement 14-4 

user routine 14-5 
program 

beginning 1-3, 2-1 

communication 12-1 

compiling 1-14, 4-1 

concepts 9-1 

creating a multitask program 9-5 

data management from 10-1 

definition 9-2 

ending 1-5, 2-35 
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program (continued) 

entering 1-6, 3-1 

execute 

with session manager 6-1 

finding 12-4 

load 

from a program 12-2 

from a virtual terminal 13-2 

logic, controlling 2-30 

modifying 3-5 

multitask 9-5 

name 9-5 

opening a data set 10-14 

overlay 9-12 

repetitive loops 2-32 

sequencing functions 2-30 

single-task 9-3 

source 1-5 

spooling output 16-1 

structure 9-2 

task error exit routine 7-17 
program function (PF) keys 

use in terminal support B-1 

use with attention lists B-3 
program messages 

See messages, program 
program preparation 

See SEDXASM Event Driven Language compiler 
PROGRAM statement 

example 2-1 

identifying data sets 2-2 

simplest form 2-1 

specifying overlay program 9-12 

starting a program 1-3 
PROGSTOP instruction 

overview 2-35 
protected field 

defined 8-2 

displaying 8-28 

writing 8-37 
pulse digital output 14-10 

Q 

queue processing 

description 18-1 

example 18-2 

putting data into a queue 18-1 

retrieving data from a queue 18-2 
queue, job 6-5 



R 

read 

all unprotected fields 8-43 

alphanumeric data from a terminal 2-9 

analog input 14-8 

data 

across partitions 12-12 
from a screen 8-1 
from a terminal 2-8 
from disk 2-7 
from diskette 2-7 
from tape 2-8 
into data area 2-7 

data across partitions 12-12 

digital input 14-9 

directly 2-7 

from a roll screen 8-3 

from a static screen 8-8 

modified data 8-41 

multivolume tape data set 11-6 

nonlabeled tape 11-10 

one line from a terminal 8-3 

sequentially 2-7, 2-8 

standard-label tape 11-2 

tape 11-1 
READ instruction 

reading a multivolume tape data set 11-6 

reading a nonlabeled tape 11-10 

reading a standard-label tape 11-2 

reading data across partitions 12-12 
READTEXT instruction 

gather read operations 8-26 

processing interrupts B-2 

reading a character string 2-6 

reading data from a static screen 8-8, 8-20 

reading unprotected data 8-27, 8-29 

retrieving prompts from a data set 17-8 

using on 3101 terminals 8-30 
records 

defined 2-7 
reentrant code 

coding guideUnes 19-1 

definition 19-1 

examples 19-3 

when to use 19-1 

writing 19-1 
relational statements 2-30 
release 

data set from a program 10-8 
rename 

data set from a program 10-9 
repetitive loops 2-32 
resources 

sharing 12-6 
restart 

a program 7-1 
retrieve 

data 1-3 
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retrieve (continued) 

data from a queue 18-2 

program messages 17-6 

screen format 8-28 

unprotected data 8-29 
return codes 

SIMDATA subroutine C-12 

SIMOPEN subroutine C-7 

SIMPROT subroutine C-10 

defined 7-14 

using to diagnose problems 7-14 
RETURN instruction 

overview 9-6 
roll screen 

defined 8-1 

displaying data 8-4 

example 8-4 

reading data 8-3 

writing data 8-4 
running programs 

methods 6-1 

with session manager 1-20 



save 

data set 3-4 
SBIO instruction 
description 14-7 
ftinction 14-3 
scatter write 

coding for device independence 8-26 
defined 8-11 

displaying unprotected data 8-29 
simulating 8-38 
screen 
format 

for the 3101 terminal 8-35 
for the 3151, 3161, 3163, 3164 terminals 8-35 
for 4978, 4979, or 4980 8-11 
retrieving 8-28 
images 

buffer sizes C-12 
retrieving and displaying 8-28 
using SIMAGE subroutines C-4 
reading 8-1 
roll screen 

See roll screen 
static screen 

See static screen 
writing 8-1 
SCREEN instruction 

coding description 15-2 
overview 1 5-2 
secondary -control-statement data set 5-10 
secondary program 13-1 
segment, overlay 
defined 9-9 



segment, overlay (continued) 

link editing 5-7 
send 

data to virtual terminal 13-2 
sensor-based I/O 

assignments 14-3 

statement overview 14-3 
SENSORIO statement 

relationship with instructions 14-3 
sequencing instructions, program 2-30 
serially reusable resource (SRR) 

description 12-6 
session manager 

background option 6-2 

data management menu 1-12 

entering user ID 1-6 

executing a program 1-20, 6-1 

executing a program in the background 

loading 1-6 

program preparation 1-14 

text editing menu 1-7 
set 

breakpoint 7-5 

end-of-data from a program 10-10 
SETEOD subroutine 10-21 
sharing resources 12-6 
single-task program 9-3 
source program 

compiling 1-11 

creating a new data set 3-2 

defined 1-5 

entering into a data set 1-6, 3-1 

modifying 3-5 

changing a line 3-5 

deleting a line 3-7 

deleting more than one line 3-8 

inserting a line 3-6 

moving lines 3-9 

saving a data set 3-4 
spaces, defining 2-4 
specify 

data set 6-3 
SPECPI process interrupt routine 14-5 
SPECPIRT instruction 

coding description 14-10 

function 14-3 
spoohng 

controUing from a program 16-1 

description 16-1 

finding if spooling is active 16-7 

output into several jobs 16-8 

output of a program 16-1 

preventing spooling 16-8 

printing spooled output 16-6 

programming considerations 16-9 

reasons for using 16-1 

spool control record 
example 1 6-2 
format 1 6-2 
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spooling (continued) 

spool control record (continued) 
functions 16-1 

stopping spooling 16-7 
standard labels, tape 

bypassing 11-4 

closing 11-4 

defined 11-1 

reading 11-2 

writing 11-3 
start 

task 9-2 

task from a program 12-4 
static screen 

blanking a blinking field 8-38 

change attribute byte 8-39 

changing attribute 8-35 

creating a screen 8-16 

creating data entry field 8-40 

creating unprotected fields 8-37 

defined 8-2 

defining a screen 8-17 

defining a static screen 8-6 

designing for device independence 8-24 

displaying a static screen 8-19 

enqueuing 8-35 

erasing individual fields 8-38 

erasing the screen 8-7, 8-36 

erasing to end of screen 8-42 

example 8-9, 8-22 

getting exclusive access 8-7, 8-18 

link editing a program 8-21 

positioning the cursor 8-7, 8-19 

prompting for data 8-7 

reading a screen image 8-18 

reading all unprotected fields 8-43 

reading data 8-20 

reading modified data 8-41 

sample program (4978, 4979, or 4980) 8-13 

scatter write 8-38 

two ways to define 8-5 

waiting for a response 8-8, 8-19 

writing Winking fields 8-38 

writing data 8-20 

writing nondisplay fields 8-37 

writing protected fields 8-37 

3101 sample program 8-44 
stop 

program 7-1 
storage 

comparing 2-3 1 

reading data into 2-7 

reserving 2-2 

unmapped 9-13 

writing data from 2-28 
STORBLK statement 

setting up unmapped storage 9-14 



store 

program messages 17-4 
strings, character 2-4 
submit 

program from a program 6-5 
SUBROUT statement 

overview 9-6 
subroutines 

$DISKUT3 10-1 

SIMAGE C-3 

caUing 9-6, 9-8 

defining 9-7 

DSOPEN 10-14 

examples 9-8 

passing parameters 9-7 

program 9-6 

SETEOD 10-21 
subtract 

consecutive integers 2-18 

double-precision integers 2-17 

extended-precision floating point 2-22 

floating-point data 2-22 

integers 2-17 
SUBTRACT instrucdon 

subtracting consecutive integers 2-18 

subtracting double-precision integers 2-17 

subtracting integers 2-17 
supervisor 

states 9-1 
SWAP instruction 

accessing unmapped storage 9-15 
symbol 

assign a value to 2-5 
synchronizing tasks 12-8 



tape 

adding records to a file 11-11 
labels 11-1, A-1 
nonlabeled 

defined 11-1 

defining 11-8 

initializing 11-9 

reading 11-10 

when to use 11-1 

writing 11-10 
processing a tape containing more than one data 

set 11-5 
reading a multivolume data set 11-6 
standard-label 

bypassing 11-4 

closing 11-4 

defined 11-1 

reading 11-2 

when to use 11-1 

writing 11-3 
tapemark 11-1 
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task 

basic executable unit 9-2 

concepts 9-1 

defining 2-1 

definition 9-1 

initiating 9-2 

multitask program 9-5 

overview 9-1 

primary task 9-5 

priority 9-1 

single-task program 9-3 

starting 9-2 

starting from a program 12-4 

states 9-1 

structure 9-1 

synchronizing 9-6, 12-8 
task code word 

accessing 7-14 

defined 7-14 

diagnosing errors with ACCA devices 7-15 
task error exit routine 

description 7-16 

example 7-17 

including in a program 7-17 

system-supplied 7-16 
TCBGET instruction 

accessing remainder of divide 2-20 
TERM CTRL instruction 

displaying a static screen 8-19 

positioning the cursor 8-7 

use on 3101 terminals 

use on 3151 terminals 

use on 3161 terminals 

use on 3163 terminals 

use on 3164 terminals 
terminal 

read 

alphanumeric data 

write 

alphanumeric data 
numeric data 2-30 
terminal I/O 

advance input B-3 

sample static screen program (4978, 4979, 
4980) 8-13 
TERMINAL statement 

defining virtual terminals 13-1 
text buffers, defining 2-6 
text editing utilities 

full-screen editor 3-1 
text messages, defining 2-6 
TEXT statement 

defining buffers 2-6 

defining messages 2-6 

structure 2-6 
trace 

program execution 7-1 



8-30 
8-30 
8-30 
8-30 
8-30 
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2-29 



u 

unmapped storage 

accessing 9-15 

defined 9-13 

displaying 7-9 

example 9-16 

obtaining 9-14 

overview 9-13 

releasing 9-15 

setting up 9-14 
unprotected field 

defined 8-2 

displaying 8-28 

reading from static screen 

retrieving 8-29 
UPDT APE routine 11-11 



8-20 



variable fields in program messages 17-2 
vary 

processing a tape containing more than one data 
set 11-5 
virtual terminals 

defining 13-1 

definition of 13-1 

examples of use 13-1 

interprogram dialogue 13-2 

loading from a virtual terminal 13-2 

sample programs 13-3 
volume 

independence 1 0-20 
volume serial, tape 11-2 

w 

WAIT instruction 

synchronizing tasks 9-6 

synchronizing tasks in other partitions 1 2-8 

use of WAIT KEY in terminal support B-2 

waiting for operator response 8-8, 8-19, B-2 
WHERES instruction 

finding a program 12-4 
write 

alphanumeric data to a terminal 2-29 

analog output 14-8 

bhnking field 8-38 

data to a screen 8-1 

digital output 14-9 

directly 2-28 

from a data area 2-28 

nondisplay field 8-37 

nonlabeled tape 11-10 

numeric data to a terminal 2-30 

protected fields 8-37 

sequentially 2-28, 2-29 

source data set 1-9 

standard-label tape 11-3 
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write (continued) 

tape 11-1 

to disk 2-28 

to diskette 2-28 

to static screen 8-8, 8-20 

to tape 2-29 

to terminal 2-29 
WRITE instruction 

reentrant code 19-1 

writing a nonlabeled tape 11-10 

writing a standard-label tape 11-3 

writing to disk 2-28 

writing to diskette 2-28 

writing to tape 2-29 



XYPLOT instruction 
overview 15-2 



YTPLOT instruction 

coding description 15-2 
overview 15-2 

Numerics 

3101 Display Terminal 

attribute characters 8-32 
changing the attribute byte 8-36 
compatibility limitation 8-25 
converting 4978 screens 8-31 
data stream 8-32 
defining screen format 8-35 
device independence 8-24 
erasing the screen 8-36 
PF key support B-2 
protecting the first field 8-36 
read data from a screen 8-31 
reading modified data 8-40, 8-42 
sample static screen program 8-44 
transmitting data from 8-32 
write data to a screen 8-31 

3151 Display Terminal 

additional buffer requirements 8-34 

attribute characters 8-32 

data stream 8-33 

PF key support B-2 

reading modified data 8-40 

write data to a screen 8-31 

3 1 1 emulation mode 8-1 

3161 Display Terminal 

additional buffer requirements 8-34 

attribute characters 8-32 

data stream 8-33 

PF key support B-2 

read data from a screen 8-31 

reading modified data 8-40 



3161 Display Terminal (continued) 
write data to a screen 8-31 
3101 emulation mode 8-1 

3163 Display Terminal 

additional buffer requirements 8-34 

attribute characters 8-32 

data stream 8-33 

PF key support B-2 

read data from a screen 8-3 1 

reading modified data 8-40 

write data to a screen 8-31 

3101 emulation mode 8-1 

3 1 64 Display Terminal 

additional buffer requirements 8-34 

attribute characters 8-32 

data stream 8-33 

PF key support B-2 

read data from a screen 8-31 

reading modified data 8-40 

write data to a screen 8-31 

3101 emulation mode 8-1 

4978 Display Station 

device independence 8-24 

static screen sample program 8-13 

4979 Display Station 

device independence 8-24 

static screen sample program 8-13 
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